Debian Codegraph @

manual/conversion.rst

raw
1 .. _conversion:
2
3 E-book conversion
4 ===================
5
6 calibre has a conversion system that is designed to be very easy to use.
7 Normally, you just add a book to calibre, click convert and calibre will try hard
8 to generate output that is as close as possible to the input. However, calibre
9 accepts a very large number of input formats, not all of which are as suitable
10 as others for conversion to e-books. In the case of such input formats, or if
11 you just want greater control over the conversion system, calibre has a lot of
12 options to fine tune the conversion process. Note however that calibre's
13 conversion system is not a substitute for a full blown e-book editor. To edit
14 e-books, I recommend first converting them to EPUB or AZW3 using calibre and
15 then using the :guilabel:`Edit book` feature to get them into perfect shape. You can then
16 use the edited e-book as input for conversion into other formats in calibre.
17
18 This document will refer mainly to the conversion settings as found in the
19 conversion dialog, pictured below. All these settings are also available via
20 command line interface to conversion, documented at :doc:`generated/en/ebook-convert`. In
21 calibre, you can obtain help on any individual setting by holding your mouse over
22 it, a tooltip will appear describing the setting.
23
24 .. image:: images/conv_dialog.png
25 :align: center
26 :alt: E-book conversion dialog
27 :class: half-width-img
28
29 .. contents:: Contents
30 :depth: 1
31 :local:
32
33 .. _conversion-introduction:
34
35 Introduction
36 -------------
37
38 .. |dbgi| image:: images/debug.png
39 :align: middle
40 :alt: Debug icon
41
42 The first thing to understand about the conversion system is that it is designed as a pipeline.
43 Schematically, it looks like this:
44
45 .. image:: images/pipeline.png
46 :align: center
47 :alt: The conversion pipeline
48
49 The input format is first converted to XHTML by the appropriate *Input plugin*.
50 This HTML is then *transformed*. In the last step, the processed XHTML is converted
51 to the specified output format by the appropriate *Output plugin*. The results
52 of the conversion can vary greatly, based on the input format. Some formats
53 convert much better than others. A list of the best source formats for conversion
54 is available :ref:`here <best-source-formats>`.
55
56 The transforms that act on the XHTML output are where all the work happens. There are various
57 transforms, for example, to insert book metadata as a page at the start of the book,
58 to detect chapter headings and automatically create a Table of Contents, to proportionally
59 adjust font sizes, et cetera. It is important to remember that all the transforms act on the
60 XHTML output by the *Input plugin*, not on the input file itself. So, for example, if you ask calibre
61 to convert an RTF file to EPUB, it will first be converted to XHTML internally,
62 the various transforms will be applied to the XHTML and then the *Output plugin* will
63 create the EPUB file, automatically generating all metadata, Table of Contents, et cetera.
64
65 You can see this process in action by using the debug option |dbgi|. Just specify the path to
66 a folder for the debug output. During conversion, calibre will place the XHTML generated by
67 the various stages of the conversion pipeline in different sub-folders.
68 The four sub-folders are:
69
70 .. table:: Stages of the conversion pipeline
71
72 ========== =============
73 Folder Description
74 ========== =============
75 input This contains the HTML output by the Input plugin. Use this to debug the Input plugin.
76 parsed The result of pre-processing and converting to XHTML the output from the Input plugin. Use to debug structure detection.
77 structure Post structure detection, but before CSS flattening and font size conversion. Use to debug font size conversion and CSS transforms.
78 processed Just before the e-book is passed to the Output plugin. Use to debug the Output plugin.
79 ========== =============
80
81 If you want to edit the input document a little before having calibre convert it, the best thing to
82 do is edit the files in the :file:`input` sub-folder, then zip it up, and use the ZIP file as the
83 input format for subsequent conversions. To do this use the :guilabel:`Edit meta information` dialog
84 to add the ZIP file as a format for the book and then, in the top left corner of the conversion dialog,
85 select ZIP as the input format.
86
87 This document will deal mainly with the various transforms that operate on the intermediate XHTML
88 and how to control them. At the end are some tips specific to each input/output format.
89
90 Look & feel
91 -------------
92
93 .. contents:: Contents
94 :depth: 1
95 :local:
96
97 This group of options controls various aspects of the look and feel of the converted e-book.
98
99 .. _font-size-rescaling:
100
101 Fonts
102 ~~~~~~~~~~~~~~~~~~~~~~~
103
104 One of the nicest features of the e-reading experience is the ability to easily adjust font sizes to
105 suit individual needs and lighting conditions. calibre has sophisticated algorithms to ensure that
106 all the books it outputs have consistent font sizes, no matter what font sizes are specified
107 in the input document.
108
109 The base font size of a document is the most common font size in that document,
110 i.e., the size of the bulk of text in that document. When you specify a
111 :guilabel:`Base font size`, calibre automatically rescales all font sizes in the document
112 proportionately, so that the most common font size becomes the specified base font size and other
113 font sizes are rescaled appropriately. By choosing a larger base font size, you can make the fonts
114 in the document larger and vice versa. When you set the base font size, for best results, you should
115 also set the font size key.
116
117 Normally, calibre will automatically choose a base font size appropriate to the output profile you
118 have chosen (see :ref:`page-setup`). However, you can override this here in case the default is
119 not suitable for you.
120
121 The :guilabel:`Font size key` option lets you control how non-base font sizes are rescaled.
122 The font rescaling algorithm works using a font size key, which is simply a comma-separated
123 list of font sizes. The font size key tells calibre how many "steps" bigger or smaller a given font
124 size should be compared to the base font size. The idea is that there should be a limited number
125 of font sizes in a document. For example, one size for the body text, a couple of sizes for
126 different levels of headings and a couple of sizes for super/sub scripts and footnotes. The
127 font size key allows calibre to compartmentalize the font sizes in the input documents into
128 separate "bins" corresponding to the different logical font sizes.
129
130 Let's illustrate with an example.
131 Suppose the source document we are converting was produced by someone with excellent
132 eyesight and has a base font size of 8pt. That means the bulk of the text in the document is sized
133 at 8pts, while headings are somewhat larger (say 10 and 12pt) and footnotes somewhat smaller at 6pt.
134 Now if we use the following settings::
135
136 Base font size : 12pt
137 Font size key : 7, 8, 10, 12, 14, 16, 18, 20
138
139 The output document will have a base font size of 12pt, headings of 14 and 16pt and footnotes of 8pt.
140 Now suppose we want to make the largest heading size stand out more and make the footnotes a
141 little larger as well. To achieve this, the font key should be changed to::
142
143 New font size key : 7, 9, 12, 14, 18, 20, 22
144
145 The largest headings will now become 18pt, while the footnotes will become 9pt. You can
146 play with these settings to try and figure out what would be optimum for you by using the
147 font rescaling wizard, which can be accessed by clicking the little button next to the
148 :guilabel:`Font size key` setting.
149
150 All the font size rescaling in the conversion can also be disabled here, if you would
151 like to preserve the font sizes in the input document.
152
153 A related setting is :guilabel:`Line height`. Line height controls the vertical height of
154 lines. By default, (a line height of 0), no manipulation of line heights is performed. If
155 you specify a non-default value, line heights will be set in all locations that don't specify their
156 own line heights. However, this is something of a blunt weapon and should be used sparingly.
157 If you want to adjust the line heights for some section of the input, it's better to use
158 the :ref:`Extra CSS <extra-css>`.
159
160 In this section you can also tell calibre to embed any referenced fonts into
161 the book. This will allow the fonts to work on reader devices even if they are
162 not available on the device.
163
164 Text
165 ~~~~~~~~
166
167 Text can be either justified or not. Justified text has extra spaces between
168 words to give a smooth right margin. Some people prefer justified text, others
169 do not. Normally, calibre will preserve the justification in the original
170 document. If you want to override it you can use the :guilabel:`Text
171 justification` option in this section.
172
173 You can also tell calibre to :guilabel:`Smarten punctuation` which will replace
174 plain quotes, dashes and ellipses with their typographically correct alternatives.
175 Note that this algorithm is not perfect so it is worth reviewing the results.
176 The reverse, namely, :guilabel:`Unsmarted punctuation` is also available.
177
178 Finally, there is :guilabel:`Input character encoding`. Older documents
179 sometimes don't specify their character encoding. When converted, this can
180 result in non-English characters or special characters like smart quotes being
181 corrupted. calibre tries to auto-detect the character encoding of the source
182 document, but it does not always succeed. You can force it to assume a
183 particular character encoding by using this setting. `cp1252` is a common
184 encoding for documents produced using Windows software. You should also read
185 :ref:`char-encoding-faq` for more on encoding issues.
186
187 Layout
188 ~~~~~~~~~~~~~~~~~~~
189
190 Normally, paragraphs in XHTML are rendered with a blank line between them and no leading text
191 indent. calibre has a couple of options to control this. :guilabel:`Remove spacing between paragraphs`
192 forcefully ensure that all paragraphs have no inter paragraph spacing. It also sets the text
193 indent to 1.5em (can be changed) to mark the start of every paragraph.
194 :guilabel:`Insert blank line` does the
195 opposite, guaranteeing that there is exactly one blank line between each pair of paragraphs.
196 Both these options are very comprehensive, removing spacing, or inserting it for *all* paragraphs
197 (technically <p> and <div> tags). This is so that you can just set the option and be sure that
198 it performs as advertised, irrespective of how messy the input file is. The one exception is
199 when the input file uses hard line breaks to implement inter-paragraph spacing.
200
201 If you want to remove the spacing between all paragraphs, except a select few, don't use these
202 options. Instead add the following CSS code to :ref:`Extra CSS <extra-css>`::
203
204 p, div { margin: 0pt; border: 0pt; text-indent: 1.5em }
205 .spacious { margin-bottom: 1em; text-indent: 0pt; }
206
207 Then, in your source document, mark the paragraphs that need spacing with `class="spacious"`.
208 If your input document is not in HTML, use the Debug option, described in the Introduction to get HTML
209 (use the :file:`input` sub-folder).
210
211 Another useful option is :guilabel:`Linearize tables`. Some badly designed
212 documents use tables to control the layout of text on the page. When converted
213 these documents often have text that runs off the page and other artifacts.
214 This option will extract the content from the tables and present it in a linear
215 fashion. Note that this option linearizes *all* tables, so only use it if you
216 are sure the input document does not use tables for legitimate purposes, like
217 presenting tabular information.
218
219 Styling
220 ~~~~~~~~~~
221
222 .. _extra-css:
223
224 The :guilabel:`Extra CSS` option allows you to specify arbitrary CSS that will
225 be applied to all HTML files in the input. This CSS is applied with very high
226 priority and so should override most CSS present in the **input document**
227 itself. You can use this setting to fine tune the presentation/layout of your
228 document. For example, if you want all paragraphs of class `endnote` to be
229 right aligned, just add::
230
231 .endnote { text-align: right }
232
233 or if you want to change the indentation of all paragraphs::
234
235 p { text-indent: 5mm; }
236
237 :guilabel:`Extra CSS` is a very powerful option, but you do need an understanding of how CSS works
238 to use it to its full potential. You can use the debug pipeline option described above to see what
239 CSS is present in your input document.
240
241 A simpler option is to use :guilabel:`Filter style information`. This allows
242 you to remove all CSS properties of the specified types from the document. For
243 example, you can use it to remove all colors or fonts.
244
245 Transform styles
246 ~~~~~~~~~~~~~~~~~~~
247
248 This is the most powerful styling related facility. You can use it to define
249 rules that change styles based on various conditions. For example you can use
250 it to change all green colors to blue, or remove all bold styling from the text
251 or color all headings a certain color, etc.
252
253 Transform HTML
254 ~~~~~~~~~~~~~~~~~~~
255
256 Similar to transform styles, but allows you to make changes to the HTML content
257 of the book. You can replace one tag with another, add classes or other
258 attributes to tags based on their content, etc.
259
260
261
262 .. _page-setup:
263
264 Page setup
265 -------------
266
267 The :guilabel:`Page setup` options are for controlling screen layout, like
268 margins and screen sizes. There are options to setup page margins, which will
269 be used by the output plugin, if the selected output format supports page
270 margins. In addition, you should choose an Input profile and an output profile.
271 Both sets of profiles basically deal with how to interpret measurements in the
272 input/output documents, screen sizes and default font rescaling keys.
273
274 If you know that the file you are converting was intended to be used on a
275 particular device/software platform, choose the corresponding input profile,
276 otherwise just choose the default input profile. If you know the files you are
277 producing are meant for a particular device type, choose the corresponding
278 output profile. Otherwise, choose one of the Generic output profiles. If you
279 are converting to MOBI or AZW3 then you will almost always want to choose one
280 of the Kindle output profiles. Otherwise, your best bet for modern E-book
281 reading devices is to choose the :guilabel:`Generic e-ink HD` output profile.
282
283 The output profile also controls the screen size. This will cause, for example,
284 images to be auto-resized to be fit to the screen in some output formats. So
285 choose a profile of a device that has a screen size similar to your device.
286
287
288 .. _heuristic-processing:
289
290 Heuristic processing
291 ---------------------
292
293 Heuristic processing provides a variety of functions which can be used to try and detect and correct
294 common problems in poorly formatted input documents. Use these functions if your input document suffers
295 from poor formatting. Because these functions rely on common patterns, be aware that in some cases an
296 option may lead to worse results, so use with care. As an example, several of these options will
297 remove all non-breaking-space entities, or may include false positive matches relating to the function.
298
299 :guilabel:`Enable heuristic processing`
300 This option activates calibre's :guilabel:`Heuristic processing` stage of the conversion pipeline.
301 This must be enabled in order for various sub-functions to be applied
302
303 :guilabel:`Unwrap lines`
304 Enabling this option will cause calibre to attempt to detect and correct hard line breaks that exist
305 within a document using punctuation clues and line length. calibre will first attempt to detect whether
306 hard line breaks exist, if they do not appear to exist calibre will not attempt to unwrap lines. The
307 line-unwrap factor can be reduced if you want to 'force' calibre to unwrap lines.
308
309 :guilabel:`Line-unwrap factor`
310 This option controls the algorithm calibre uses to remove hard line breaks. For example, if the value of this
311 option is 0.4, that means calibre will remove hard line breaks from the end of lines whose lengths are less
312 than the length of 40% of all lines in the document. If your document only has a few line breaks which need
313 correction, then this value should be reduced to somewhere between 0.1 and 0.2.
314
315 :guilabel:`Detect and markup unformatted chapter headings and sub headings`
316 If your document does not have chapter headings and titles formatted differently from the rest of the text,
317 calibre can use this option to attempt to detect them and surround them with heading tags. <h2> tags are used
318 for chapter headings; <h3> tags are used for any titles that are detected.
319
320 This function will not create a TOC, but in many cases it will cause calibre's default chapter detection settings
321 to correctly detect chapters and build a TOC. Adjust the XPath under Structure detection if a TOC is not automatically
322 created. If there are no other headings used in the document then setting "//h:h2" under Structure detection would
323 be the easiest way to create a TOC for the document.
324
325 The inserted headings are not formatted, to apply formatting use the :guilabel:`Extra CSS` option under
326 the Look and Feel conversion settings. For example, to center heading tags, use the following::
327
328 h2, h3 { text-align: center }
329
330 :guilabel:`Renumber sequences of <h1> or <h2> tags`
331 Some publishers format chapter headings using multiple <h1> or <h2> tags sequentially.
332 calibre's default conversion settings will cause such titles to be split into two pieces. This option
333 will re-number the heading tags to prevent splitting.
334
335 :guilabel:`Delete blank lines between paragraphs`
336 This option will cause calibre to analyze blank lines included within the
337 document. If every paragraph is interleaved with a blank line, then
338 calibre will remove all those blank paragraphs. Sequences of multiple
339 blank lines will be considered scene breaks and retained as a single
340 paragraph. This option differs from the :guilabel:`Remove paragraph
341 spacing` option under :guilabel:`Look and Feel` in that it actually
342 modifies the HTML content, while the other option modifies the document
343 styles. This option can also remove paragraphs which were inserted using
344 calibre's :guilabel:`Insert blank line` option.
345
346 :guilabel:`Ensure scene breaks are consistently formatted`
347 With this option calibre will attempt to detect common scene-break markers and ensure that they are center aligned.
348 'Soft' scene break markers, i.e. scene breaks only defined by extra white space, are styled to ensure that they
349 will not be displayed in conjunction with page breaks.
350
351 :guilabel:`Replace scene breaks`
352 If this option is configured then calibre will replace scene break markers it finds with the replacement text specified by the
353 user. Please note that some ornamental characters may not be supported across all reading devices.
354
355 In general you should avoid using HTML tags, calibre will discard any tags and use pre-defined markup. <hr />
356 tags, i.e. horizontal rules, and <img> tags are exceptions. Horizontal rules can optionally be specified with styles, if you
357 choose to add your own style be sure to include the 'width' setting, otherwise the style information will be discarded. Image
358 tags can used, but calibre does not provide the ability to add the image during conversion, this must be done after the fact using
359 the 'Edit book' feature.
360
361 Example image tag (place the image within an 'Images' folder inside the EPUB after conversion):
362 <img style="width:10%" src="../Images/scenebreak.png" />
363
364 Example horizontal rule with styles:
365 <hr style="width:20%;padding-top: 1px;border-top: 2px ridge black;border-bottom: 2px groove black;"/>
366
367 :guilabel:`Remove unnecessary hyphens`
368 calibre will analyze all hyphenated content in the document when this option is enabled. The document itself is used
369 as a dictionary for analysis. This allows calibre to accurately remove hyphens for any words in the document in any language,
370 along with made-up and obscure scientific words. The primary drawback is words appearing only a single time in the document
371 will not be changed. Analysis happens in two passes, the first pass analyzes line endings. Lines are only unwrapped if the
372 word exists with or without a hyphen in the document. The second pass analyzes all hyphenated words throughout the document,
373 hyphens are removed if the word exists elsewhere in the document without a match.
374
375 :guilabel:`Italicize common words and patterns`
376 When enabled, calibre will look for common words and patterns that denote italics and italicize them. Examples are common text
377 conventions such as ~word~ or phrases that should generally be italicized, e.g. latin phrases like 'etc.' or 'et cetera'.
378
379 :guilabel:`Replace entity indents with CSS indents`
380 Some documents use a convention of defining text indents using non-breaking space entities. When this option is enabled calibre will
381 attempt to detect this sort of formatting and convert them to a 3% text indent using CSS.
382
383 .. _search-replace:
384
385 Search & replace
386 ---------------------
387
388 These options are useful primarily for conversion of PDF documents or OCR conversions, though they can
389 also be used to fix many document specific problems. As an example, some conversions can leave behind page
390 headers and footers in the text. These options use regular expressions to try and detect headers, footers,
391 or other arbitrary text and remove or replace them. Remember that they operate on the intermediate XHTML produced
392 by the conversion pipeline. There is a wizard to help you customize the regular expressions for
393 your document. Click the magic wand beside the expression box, and click the 'Test' button after composing
394 your search expression. Successful matches will be highlighted in Yellow.
395
396 The search works by using a Python regular expression. All matched text is simply removed from
397 the document or replaced using the replacement pattern. The replacement pattern is optional, if left blank
398 then text matching the search pattern will be deleted from the document. You can learn more about regular expressions
399 and their syntax at :ref:`regexptutorial`.
400
401 .. _structure-detection:
402
403 Structure detection
404 ---------------------
405
406 Structure detection involves calibre trying its best to detect structural elements in the input document, when they are not
407 properly specified. For example, chapters, page breaks, headers, footers, etc. As you can imagine, this process varies widely
408 from book to book. Fortunately, calibre has very powerful options to control this. With power comes complexity, but if once you
409 take the time to learn the complexity, you will find it well worth the effort.
410
411 Chapters and page breaks
412 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
413
414 calibre has two sets of options for :guilabel:`chapter detection` and :guilabel:`inserting page breaks`. This can sometimes be
415 slightly confusing, as by default, calibre will insert page breaks before detected chapters as well as the locations detected by
416 the page breaks option. The reason for this is that there are often locations where page breaks should be inserted that are not
417 chapter boundaries. Also, detected chapters can be optionally inserted into the auto generated Table of Contents.
418
419 calibre uses *XPath*, a powerful language to allow the user to specify chapter boundaries/page breaks. XPath can seem a little daunting
420 to use at first, fortunately, there is a :ref:`XPath tutorial <xpath-tutorial>` in the User Manual. Remember that Structure detection
421 operates on the intermediate XHTML produced by the conversion pipeline. Use the debug option described in the
422 :ref:`conversion-introduction` to figure out the appropriate settings for your book. There is also a button for a XPath wizard
423 to help with the generation of simple XPath expressions.
424
425 By default, calibre uses the following expression for detecting chapters::
426
427 //*[((name()='h1' or name()='h2') and re:test(., 'chapter|book|section|part\s+', 'i')) or @class = 'chapter']
428
429 This expression is rather complex, because it tries to handle a number of common cases simultaneously. What it means
430 is that calibre will assume chapters start at either `<h1>` or `<h2>` tags that have any of the words
431 `(chapter, book, section or part)` in them or that have the `class="chapter"` attribute.
432
433 A related option is :guilabel:`Chapter mark`, which allows you to control what calibre does when it detects a chapter. By default,
434 it will insert a page break before the chapter. You can have it insert a ruled line instead of, or in addition to the page break.
435 You can also have it do nothing.
436
437 The default setting for detecting page breaks is::
438
439 //*[name()='h1' or name()='h2']
440
441 which means that calibre will insert page breaks before every `<h1>` and `<h2>` tag by default.
442
443 .. note::
444
445 The default expressions may change depending on the input format you are converting.
446
447 Miscellaneous
448 ~~~~~~~~~~~~~~
449
450 There are a few more options in this section.
451
452 :guilabel:`Insert metadata as page at start of book`
453 One of the great things about calibre is that it allows you to maintain very complete metadata
454 about all of your books, for example, a rating, tags, comments, etc. This option will create
455 a single page with all this metadata and insert it into the converted e-book, typically just
456 after the cover. Think of it as a way to create your own customised book jacket.
457
458 :guilabel:`Remove first image`
459 Sometimes, the source document you are converting includes the cover as part of the book, instead
460 of as a separate cover. If you also specify a cover in calibre, then the converted book will have
461 two covers. This option will simply remove the first image from the source document, thereby
462 ensuring that the converted book has only one cover, the one specified in calibre.
463
464
465 Table of Contents
466 ------------------
467
468 When the input document has a Table of Contents in its metadata, calibre will just use that. However,
469 a number of older formats either do not support a metadata based Table of Contents, or individual
470 documents do not have one. In these cases, the options in this section can help you automatically
471 generate a Table of Contents in the converted e-book, based on the actual content in the input document.
472
473 .. note:: Using these options can be a little challenging to get exactly right.
474 If you prefer creating/editing the Table of Contents by hand, convert to
475 the EPUB or AZW3 formats and select the checkbox at the bottom of the Table
476 of Contents section of the conversion dialog that says
477 :guilabel:`Manually fine-tune the Table of Contents after conversion`.
478 This will launch the ToC Editor tool after the conversion. It allows you to
479 create entries in the Table of Contents by simply clicking the place in the
480 book where you want the entry to point. You can also use the ToC Editor by
481 itself, without doing a conversion. Go to :guilabel:`Preferences->Interface->Toolbars`
482 and add the :guilabel:`ToC Editor` to the main toolbar. Then just select the book you
483 want to edit and click the :guilabel:`ToC Editor` button.
484
485 The first option is :guilabel:`Force use of auto-generated Table of Contents`. By checking this option
486 you can have calibre override any Table of Contents found in the metadata of the input document with the
487 auto generated one.
488
489 The default way that the creation of the auto generated Table of Contents works is that, calibre will first try
490 to add any detected chapters to the generated table of contents. You can learn how to customize the detection of chapters
491 in the :ref:`structure-detection` section above. If you do not want to include detected chapters in the generated
492 table of contents, check the :guilabel:`Do not add detected chapters` option.
493
494 If less than the :guilabel:`Chapter threshold` number of chapters were detected, calibre will then add any hyperlinks
495 it finds in the input document to the Table of Contents. This often works well: many input documents include a
496 hyperlinked Table of Contents right at the start. The :guilabel:`Number of links` option can be used to control
497 this behavior. If set to zero, no links are added. If set to a number greater than zero, at most that number of links
498 is added.
499
500 calibre will automatically filter duplicates from the generated Table of Contents. However, if there are some additional
501 undesirable entries, you can filter them using the :guilabel:`TOC Filter` option. This is a regular expression that
502 will match the title of entries in the generated table of contents. Whenever a match is found, it will be removed.
503 For example, to remove all entries titles "Next" or "Previous" use::
504
505 Next|Previous
506
507 The :guilabel:`Level 1,2,3 TOC` options allow you to create a sophisticated multi-level Table of Contents.
508 They are XPath expressions that match tags in the intermediate XHTML produced by the conversion pipeline. See the
509 :ref:`conversion-introduction` for how to get access to this XHTML. Also read the :ref:`xpath-tutorial`, to learn
510 how to construct XPath expressions. Next to each option is a button that launches a wizard to help with the creation
511 of basic XPath expressions. The following simple example illustrates how to use these options.
512
513 Suppose you have an input document that results in XHTML that looks like this:
514
515 .. code-block:: html
516
517 <html xmlns="http://www.w3.org/1999/xhtml">
518 <head>
519 <title>Sample document</title>
520 </head>
521 <body>
522 <h1>Chapter 1</h1>
523 ...
524 <h2>Section 1.1</h2>
525 ...
526 <h2>Section 1.2</h2>
527 ...
528 <h1>Chapter 2</h1>
529 ...
530 <h2>Section 2.1</h2>
531 ...
532 </body>
533 </html>
534
535 Then, we set the options as::
536
537 Level 1 TOC : //h:h1
538 Level 2 TOC : //h:h2
539
540 This will result in an automatically generated two level Table of Contents that looks like::
541
542 Chapter 1
543 Section 1.1
544 Section 1.2
545 Chapter 2
546 Section 2.1
547
548
549 .. warning::
550
551 Not all output formats support a multi level Table of Contents. You should first try with EPUB output. If that
552 works, then try your format of choice.
553
554 Using images as chapter titles when converting HTML input documents
555 ---------------------------------------------------------------------
556
557 Suppose you want to use an image as your chapter title, but still want calibre to be able to automatically generate a Table of Contents for you from the chapter titles.
558 Use the following HTML markup to achieve this:
559
560 .. code-block:: html
561
562 <html>
563 <body>
564 <h2>Chapter 1</h2>
565 <p>chapter 1 text...</p>
566 <h2 title="Chapter 2"><img src="chapter2.jpg" /></h2>
567 <p>chapter 2 text...</p>
568 </body>
569 </html>
570
571 Set the :guilabel:`Level 1 TOC` setting to ``//h:h2``. Then, for chapter two, calibre will take the title from the value of the ``title`` attribute on the ``<h2>`` tag, since the tag has no text.
572
573 Using tag attributes to supply the text for entries in the Table of Contents
574 -----------------------------------------------------------------------------
575
576 If you have particularly long chapter titles and want shortened versions in the
577 Table of Contents, you can use the title attribute to achieve this, for
578 example:
579
580 .. code-block:: html
581
582 <html>
583 <body>
584 <h2 title="Chapter 1">Chapter 1: Some very long title</h2>
585 <p>chapter 1 text...</p>
586 <h2 title="Chapter 2">Chapter 2: Some other very long title</h2>
587 <p>chapter 2 text...</p>
588 </body>
589 </html>
590
591 Set the :guilabel:`Level 1 TOC` setting to ``//h:h2/@title``. Then calibre will
592 take the title from the value of the ``title`` attribute on the ``<h2>`` tags,
593 instead of using the text inside the tag. Note the trailing ``/@title`` on the
594 XPath expression, you can use this form to tell calibre to get the text from any
595 attribute you like.
596
597 How options are set/saved for conversion
598 -------------------------------------------
599
600 There are two places where conversion options can be set in calibre. The first is
601 in Preferences->Conversion. These settings are the defaults for the conversion
602 options. Whenever you try to convert a new book, the settings set here will be
603 used by default.
604
605 You can also change settings in the conversion dialog for each book conversion.
606 When you convert a book, calibre remembers the settings you used for that book,
607 so that if you convert it again, the saved settings for the individual book
608 will take precedence over the defaults set in :guilabel:`Preferences`. You can
609 restore the individual settings to defaults by using the :guilabel:`Restore defaults`
610 button in the individual book conversion dialog. You can remove the
611 saved settings for a group of books by selecting all the books and then
612 clicking the :guilabel:`Edit metadata` button to bring up the bulk metadata
613 edit dialog, near the bottom of the dialog is an option to remove stored
614 conversion settings.
615
616 When you bulk convert a set of books, settings are taken in the following order (last one wins):
617
618 * From the defaults set in Preferences->Conversion
619
620 * From the saved conversion settings for each book being converted (if
621 any). This can be turned off by the option in the top left corner of the
622 Bulk conversion dialog.
623
624 * From the settings set in the Bulk conversion dialog
625
626 Note that the final settings for each book in a Bulk conversion will be saved
627 and re-used if the book is converted again. Since the highest priority in Bulk
628 Conversion is given to the settings in the Bulk conversion dialog, these will
629 override any book specific settings. So you should only bulk convert books
630 together that need similar settings. The exceptions are metadata and input
631 format specific settings. Since the Bulk conversion dialog does not have
632 settings for these two categories, they will be taken from book specific
633 settings (if any) or the defaults.
634
635 .. note::
636
637 You can see the actual settings used during any conversion by clicking the rotating icon in the lower right corner
638 and then double clicking the individual conversion job. This will bring up a conversion log
639 that will contain the actual settings used, near the top.
640
641 Format specific tips
642 ----------------------
643
644 Here you will find tips specific to the conversion of particular formats. Options specific to particular
645 format, whether input or output are available in the conversion dialog under their own section, for example
646 `TXT input` or `EPUB output`.
647
648 Convert Microsoft Word documents
649 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
650
651 calibre can automatically convert ``.docx`` files created by Microsoft Word 2007 and
652 newer. Just add the file to calibre and click convert.
653
654 .. note::
655 There is a :download_file:`demo .docx file <demos/demo.docx>`
656 that demonstrates the capabilities of the calibre conversion engine. Just
657 download it and convert it to EPUB or AZW3 to see what calibre can do.
658
659 calibre will automatically generate a Table of Contents based on headings if you mark
660 your headings with the ``Heading 1``, ``Heading 2``, etc. styles in Microsoft Word. Open
661 the output e-book in the calibre E-book viewer and click the :guilabel:`Table of Contents` button
662 to view the generated Table of Contents.
663
664 Older .doc files
665 ^^^^^^^^^^^^^^^^^
666
667 For older .doc files, you can save the document as HTML with Microsoft Word
668 and then convert the resulting HTML file with calibre. When saving as
669 HTML, be sure to use the "Save as Web Page, Filtered" option as this will
670 produce clean HTML that will convert well. Note that Word produces really messy
671 HTML, converting it can take a long time, so be patient. If you have a newer
672 version of Word available, you can directly save it as .docx as well.
673
674 Another alternative is to use the free LibreOffice. Open your .doc file in
675 LibreOffice and save it as .docx, which can be directly converted in calibre.
676
677 Convert TXT documents
678 ~~~~~~~~~~~~~~~~~~~~~~
679
680 TXT documents have no well defined way to specify formatting like bold, italics, etc, or document
681 structure like paragraphs, headings, sections and so on, but there are a variety of conventions commonly
682 used. By default calibre attempts automatic detection of the correct formatting and markup based on those
683 conventions.
684
685 TXT input supports a number of options to differentiate how paragraphs are detected.
686
687 :guilabel:`Paragraph style: Auto`
688 Analyzes the text file and attempts to automatically determine how paragraphs are defined. This
689 option will generally work fine, if you achieve undesirable results try one of the manual options.
690
691 :guilabel:`Paragraph style: Block`
692 Assumes one or more blank lines are a paragraph boundary::
693
694 This is the first.
695
696 This is the
697 second paragraph.
698
699 :guilabel:`Paragraph style: Single`
700 Assumes that every line is a paragraph::
701
702 This is the first.
703 This is the second.
704 This is the third.
705
706 :guilabel:`Paragraph style: Print`
707 Assumes that every paragraph starts with an indent (either a tab or 2+ spaces). Paragraphs end when
708 the next line that starts with an indent is reached::
709
710 This is the
711 first.
712 This is the second.
713
714 This is the
715 third.
716
717 :guilabel:`Paragraph style: Unformatted`
718 Assumes that the document has no formatting, but does use hard line breaks. Punctuation
719 and median line length are used to attempt to re-create paragraphs.
720
721 :guilabel:`Formatting style: Auto`
722 Attempts to detect the type of formatting markup being used. If no markup is used then heuristic
723 formatting will be applied.
724
725 :guilabel:`Formatting style: Heuristic`
726 Analyzes the document for common chapter headings, scene breaks, and italicized words and applies the
727 appropriate HTML markup during conversion.
728
729 :guilabel:`Formatting style: Markdown`
730 calibre also supports running TXT input though a transformation preprocessor known as Markdown. Markdown
731 allows for basic formatting to be added to TXT documents, such as bold, italics, section headings, tables,
732 lists, a Table of Contents, etc. Marking chapter headings with a leading # and setting the chapter XPath detection
733 expression to "//h:h1" is the easiest way to have a proper table of contents generated from a TXT document.
734 You can learn more about the Markdown syntax at `daringfireball <https://daringfireball.net/projects/markdown/syntax>`_.
735
736 :guilabel:`Formatting style: None`
737 Applies no special formatting to the text, the document is converted to HTML with no other changes.
738
739 .. _pdfconversion:
740
741 Convert PDF documents
742 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
743
744 PDF documents are one of the worst formats to convert from. They are a fixed page size and text placement format.
745 Meaning, it is very difficult to determine where one paragraph ends and another begins. calibre will try to unwrap
746 paragraphs using a configurable, :guilabel:`Line un-wrapping factor`. This is a scale used to determine the length
747 at which a line should be unwrapped. Valid values are a decimal
748 between 0 and 1. The default is 0.45, just under the median line length. Lower this value to include more
749 text in the unwrapping. Increase to include less. You can adjust this value in the conversion settings under :guilabel:`PDF Input`.
750
751 Also, they often have headers and footers as part of the document that will become included with the text.
752 Use the :guilabel:`Search and replace` panel to remove headers and footers to mitigate this issue. If the headers and footers are not
753 removed from the text it can throw off the paragraph unwrapping. To learn how to use the header and footer removal options, read
754 :ref:`regexptutorial`.
755
756 Some limitations of PDF input are:
757
758 * Complex, multi-column, and image based documents are not supported.
759 * Extraction of vector images and tables from within the document is also not supported.
760 * Some PDFs use special glyphs to represent ll or ff or fi, etc. Conversion of these may or may not work depending on just how they are represented internally in the PDF.
761 * Links and Tables of Contents are not supported
762 * PDFs that use embedded non-Unicode fonts to represent non-English characters will result in garbled output for those characters
763 * Some PDFs are made up of photographs of the page with OCRed text behind them. In such cases calibre uses the OCRed text, which can be very different from what you see when you view the PDF file
764 * PDFs that are used to display complex text, like right to left languages and math typesetting will not convert correctly
765
766 To re-iterate **PDF is a really, really bad** format to use as input. If you absolutely must use PDF, then be prepared for an
767 output ranging anywhere from decent to unusable, depending on the input PDF.
768
769 Comic book collections
770 ~~~~~~~~~~~~~~~~~~~~~~~~~
771
772 A comic book collection is a .cbc file. A .cbc file is a ZIP file that contains other CBZ/CBR files. In addition the
773 .cbc file must contain a simple text file called comics.txt, encoded in UTF-8. The comics.txt file must contain
774 a list of the comics files inside the .cbc file, in the form filename:title, as shown below::
775
776 one.cbz:Chapter One
777 two.cbz:Chapter Two
778 three.cbz:Chapter Three
779
780 The .cbc file will then contain::
781
782 comics.txt
783 one.cbz
784 two.cbz
785 three.cbz
786
787 calibre will automatically convert this .cbc file into an e-book with a Table of Contents pointing to each entry in comics.txt.
788
789
790 EPUB advanced formatting demo
791 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
792
793 Various advanced formatting for EPUB files is demonstrated in this :download_file:`demo file <demos/demo.epub>`.
794 The file was created from hand coded HTML using calibre and is meant to be used as a template for your own EPUB creation efforts.
795
796 The source HTML it was created from is available :download_file:`demo.zip <demos/demo.zip>`. The settings used to create the
797 EPUB from the ZIP file are::
798
799 ebook-convert demo.zip .epub -vv --authors "Kovid Goyal" --language en --level1-toc '//*[@class="title"]' --disable-font-rescaling --page-breaks-before / --no-default-epub-cover
800
801 Note that because this file explores the potential of EPUB, most of the advanced formatting is not going to work on readers less capable than calibre's built-in EPUB viewer.
802
803
804 Convert ODT documents
805 ~~~~~~~~~~~~~~~~~~~~~
806
807 calibre can directly convert ODT (OpenDocument Text) files. You should use styles to format your document and minimize the use of direct formatting.
808 When inserting images into your document you need to anchor them to the paragraph, images anchored to a page will all end up in the front of the conversion.
809
810 To enable automatic detection of chapters, you need to mark them with the built-in styles called :guilabel:`Heading 1`,
811 :guilabel:`Heading 2`, ..., :guilabel:`Heading 6` (:guilabel:`Heading 1` equates to the HTML tag ``<h1>``,
812 :guilabel:`Heading 2` to ``<h2>``, etc).
813 When you convert in calibre you can enter which style you used into the :guilabel:`Detect chapters at` box.
814 Example:
815
816 * If you mark Chapters with style :guilabel:`Heading 2`, you have to set the 'Detect chapters at' box to ``//h:h2``
817 * For a nested TOC with Sections marked with :guilabel:`Heading 2` and the Chapters marked with :guilabel:`Heading 3` you need to enter ``//h:h2|//h:h3``. On the Convert - TOC page set the :guilabel:`Level 1 TOC` box to ``//h:h2`` and the :guilabel:`Level 2 TOC` box to ``//h:h3``.
818
819 Well-known document properties (Title, Keywords, Description, Creator) are recognized and calibre will use the first image (not too small, and with good aspect-ratio) as the cover image.
820
821 There is also an advanced property conversion mode, which is activated by setting the custom property ``opf.metadata`` ('Yes or No' type) to Yes in your ODT document (File->Properties->Custom Properties).
822 If this property is detected by calibre, the following custom properties are recognized (``opf.authors`` overrides document creator)::
823
824 opf.titlesort
825 opf.authors
826 opf.authorsort
827 opf.publisher
828 opf.pubdate
829 opf.isbn
830 opf.language
831 opf.series
832 opf.seriesindex
833
834 In addition to this, you can specify the picture to use as the cover by naming
835 it ``opf.cover`` (right click, Picture->Options->Name) in the ODT. If no
836 picture with this name is found, the 'smart' method is used. As the cover
837 detection might result in double covers in certain output formats, the process
838 will remove the paragraph (only if the only content is the cover!) from the
839 document. But this works only with the named picture!
840
841 To disable cover detection you can set the custom property ``opf.nocover`` ('Yes or No' type) to Yes in advanced mode.
842
843 Converting to PDF
844 ~~~~~~~~~~~~~~~~~~~
845
846 The first, most important, setting to decide on when converting to PDF is the page
847 size. By default, calibre uses a page size of "U.S. Letter". You can change this
848 to another standard page size or a completely custom size in the :guilabel:`PDF Output`
849 section of the conversion dialog. If you are generating a PDF to be used on a
850 specific device, you can turn on the option to use the page size from the
851 :guilabel:`output profile` instead. So if your output profile is set to Kindle, calibre
852 will create a PDF with page size suitable for viewing on the small Kindle
853 screen.
854
855 Headers and Footers
856 ^^^^^^^^^^^^^^^^^^^^
857 You can insert arbitrary headers and footers on each page of the PDF by
858 specifying header and footer templates. Templates are just snippets of HTML
859 code that get rendered in the header and footer locations. For example, to
860 display page numbers centered at the bottom of every page, in green, use the following
861 footer template::
862
863 <footer><div style="margin: auto; color: green">_PAGENUM_</div></footer>
864
865 calibre will automatically replace :code:`_PAGENUM_` with the current page number. You
866 can even put different content on even and odd pages, for example the following
867 header template will show the title on odd pages and the author on even pages::
868
869 <header style="justify-content: flex-end">
870 <div class="even-page">_AUTHOR_</div>
871 <div class="odd-page"><i>_TITLE_</i></div>
872 </header>
873
874 calibre will automatically replace :code:`_TITLE_` and :code:`_AUTHOR_` with
875 the title and author of the document being converted. Setting
876 :code:`justify-content` to :code:`flex-end` will cause the text to be right
877 aligned.
878
879 You can also display text at the left and right edges and change the font size,
880 as demonstrated with this header template::
881
882 <header style="justify-content: space-between; font-size: smaller">
883 <div>_TITLE_</div>
884 <div>_AUTHOR_</div>
885 </header>
886
887 This will display the title at the left and the author at the right, in a font
888 size smaller than the main text.
889
890 You can also use the current section in templates, as shown below::
891
892 <header><div>_SECTION_</div></header>
893
894 :code:`_SECTION_` is replaced by whatever the name of the current section is. These
895 names are taken from the metadata Table of Contents in the document (the PDF
896 Outline). If the document has no table of contents then it will be replaced by
897 empty text. If a single PDF page has multiple sections, the first section on
898 the page will be used. Similarly, there is a variable named :code:`_TOP_LEVEL_SECTION_`
899 that can be used to get the name of the current top-level section.
900
901 You can even use JavaScript inside the header and footer templates, for
902 example, the following template will cause page numbers to start at 4 instead
903 of 1::
904
905 <footer>
906 <div></div>
907 <script>document.currentScript.parentNode.querySelector("div").innerHTML = "" + (_PAGENUM_ + 3)</script>
908 </footer>
909
910
911 In addition there are some more variables you can use in the headers and
912 footers, documented below:
913
914 * ``_TOTAL_PAGES_`` - total number of pages in the PDF file, useful for
915 implementing a progress counter, for example.
916 * ``_TOP_LEVEL_SECTION_PAGES_`` - total number of pages in the current top
917 level section
918 * ``_TOP_LEVEL_SECTION_PAGENUM_`` - the page number of the current page
919 within the current top level section
920 * ``_WIDTH_PIXELS_`` - the width of the header/footer area in pixels
921 * ``_HEIGHT_PIXELS_`` - the height of the header/footer area in pixels
922
923 .. note:: When adding headers and footers make sure you set the page top and
924 bottom margins to large enough values, under the :guilabel:`PDF Output`
925 section of the conversion dialog.
926
927 Printable Table of Contents
928 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
929
930 You can also insert a printable Table of Contents at the end of the PDF that
931 lists the page numbers for every section. This is very useful if you intend to
932 print out the PDF to paper. If you wish to use the PDF on an electronic device,
933 then the PDF Outline provides this functionality and is generated by default.
934
935 You can customize the look of the generated Table of contents by using the
936 Extra CSS conversion setting under the Look & feel part of the conversion
937 dialog. The default CSS used is listed below, simply copy it and make whatever
938 changes you like.
939
940 .. code-block:: css
941
942 .calibre-pdf-toc table { width: 100%% }
943
944 .calibre-pdf-toc table tr td:last-of-type { text-align: right }
945
946 .calibre-pdf-toc .level-0 {
947 font-size: larger;
948 }
949
950 .calibre-pdf-toc .level-1 td:first-of-type { padding-left: 1.4em }
951 .calibre-pdf-toc .level-2 td:first-of-type { padding-left: 2.8em }
952
953
954 Custom page margins for individual HTML files
955 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
956
957 If you are converting an EPUB or AZW3 file with multiple individual HTML files
958 inside it and you want to change the page margins for a particular HTML file
959 you can add the following style block to the HTML file using the calibre
960 E-book editor:
961
962 .. code-block:: html
963
964 <style>
965 @page {
966 margin-left: 10pt;
967 margin-right: 10pt;
968 margin-top: 10pt;
969 margin-bottom: 10pt;
970 }
971 </style>
972
973
974 Then, in the PDF output section of the conversion dialog, turn on the
975 option to :guilabel:`Use page margins from the document being converted`.
976 Now all pages generated from this HTML file will have ``10pt`` margins.