Cutlery/calibre
1
0
Fork 0
mirror of https://github.com/kovidgoyal/calibre.git synced 2025-07-09 03:04:10 -04:00
Code Issues Packages Projects Releases Wiki Activity

Remove use of |app| placeholder in user manual, as it causes problems with translations

Browse Source
This commit is contained in:
Kovid Goyal 2014-10-17 08:19:48 +05:30
parent bca48b4f2d
commit 42ca1149e5
26 changed files with 544 additions and 546 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
manual/catalogs.rst
View File

@ -3,7 +3,7 @@
Creating AZW3 • EPUB • MOBI Catalogs Creating AZW3 • EPUB • MOBI Catalogs
===================================== =====================================
|app|'s Create catalog feature enables you to create a catalog of your library in a variety of formats. This help file describes cataloging options when generating a catalog in AZW3, EPUB and MOBI formats. calibre's Create catalog feature enables you to create a catalog of your library in a variety of formats. This help file describes cataloging options when generating a catalog in AZW3, EPUB and MOBI formats.
.. contents:: .. contents::
:depth: 1 :depth: 1
@ -16,7 +16,7 @@ If you want *all* of your library cataloged, remove any search or filtering crit
If you want only *some* of your library cataloged, you have two options: If you want only *some* of your library cataloged, you have two options:
* Create a multiple selection of the books you want cataloged. With more than one book selected in |app|'s main window, only the selected books will be cataloged. * Create a multiple selection of the books you want cataloged. With more than one book selected in calibre's main window, only the selected books will be cataloged.
* Use the Search field or the Tag Browser to filter the displayed books. Only the displayed books will be cataloged. * Use the Search field or the Tag Browser to filter the displayed books. Only the displayed books will be cataloged.
To begin catalog generation, select the menu item :guilabel:`Convert books > Create a catalog of the books in your calibre library`. You may also add a :guilabel:`Create Catalog` button to a toolbar in :guilabel:`Preferences > Interface > Toolbars` for easier access to the Generate catalog dialog. To begin catalog generation, select the menu item :guilabel:`Convert books > Create a catalog of the books in your calibre library`. You may also add a :guilabel:`Create Catalog` button to a toolbar in :guilabel:`Preferences > Interface > Toolbars` for easier access to the Generate catalog dialog.
@ -131,7 +131,7 @@ To install the plugin, go to :guilabel:`Preferences > Advanced > Plugins > Get n
Additional help resources Additional help resources
--------------------------- ---------------------------
For more information on |app|'s Catalog feature, see the MobileRead forum sticky `Creating Catalogs - Start here <http://www.mobileread.com/forums/showthread.php?t=118556>`_, where you can find information on how to customize the catalog templates, and how to submit a bug report. For more information on calibre's Catalog feature, see the MobileRead forum sticky `Creating Catalogs - Start here <http://www.mobileread.com/forums/showthread.php?t=118556>`_, where you can find information on how to customize the catalog templates, and how to submit a bug report.
To ask questions or discuss calibre's Catalog feature with other users, visit the MobileRead forum `Calibre Catalogs <http://www.mobileread.com/forums/forumdisplay.php?f=236>`_. To ask questions or discuss calibre's Catalog feature with other users, visit the MobileRead forum `Calibre Catalogs <http://www.mobileread.com/forums/forumdisplay.php?f=236>`_.

166
manual/conversion.rst
View File

@ -3,22 +3,22 @@
Ebook Conversion Ebook Conversion
=================== ===================
|app| has a conversion system that is designed to be very easy to use. calibre has a conversion system that is designed to be very easy to use.
Normally, you just add a book to |app|, click convert and |app| will try hard Normally, you just add a book to calibre, click convert and calibre will try hard
to generate output that is as close as possible to the input. However, |app| to generate output that is as close as possible to the input. However, calibre
accepts a very large number of input formats, not all of which are as suitable accepts a very large number of input formats, not all of which are as suitable
as others for conversion to ebooks. In the case of such input formats, or if as others for conversion to ebooks. In the case of such input formats, or if
you just want greater control over the conversion system, |app| has a lot of you just want greater control over the conversion system, calibre has a lot of
options to fine tune the conversion process. Note however that |app|'s options to fine tune the conversion process. Note however that calibre's
conversion system is not a substitute for a full blown ebook editor. To edit conversion system is not a substitute for a full blown ebook editor. To edit
ebooks, I recommend first converting them to EPUB or AZW3 using |app| and ebooks, I recommend first converting them to EPUB or AZW3 using calibre and
then using the Edit Book feature to get them into perfect shape. You can then then using the Edit Book feature to get them into perfect shape. You can then
use the edited ebook as input for conversion into other formats in |app|. use the edited ebook as input for conversion into other formats in calibre.
This document will refer mainly to the conversion settings as found in the This document will refer mainly to the conversion settings as found in the
conversion dialog, pictured below. All these settings are also available via conversion dialog, pictured below. All these settings are also available via
command line interface to conversion, documented at :doc:`generated/|lang|/ebook-convert`. In command line interface to conversion, documented at :doc:`generated/|lang|/ebook-convert`. In
|app|, you can obtain help on any individual setting by holding your mouse over calibre, you can obtain help on any individual setting by holding your mouse over
it, a tooltip will appear describing the setting. it, a tooltip will appear describing the setting.
.. image:: images/conv_dialog.png .. image:: images/conv_dialog.png
@ -57,13 +57,13 @@ The transforms that act on the XHTML output are where all the work happens. Ther
transforms, for example, to insert book metadata as a page at the start of the book, transforms, for example, to insert book metadata as a page at the start of the book,
to detect chapter headings and automatically create a Table of Contents, to proportionally to detect chapter headings and automatically create a Table of Contents, to proportionally
adjust font sizes, et cetera. It is important to remeber that all the transforms act on the adjust font sizes, et cetera. It is important to remeber that all the transforms act on the
XHTML output by the *Input Plugin*, not on the input file itself. So, for example, if you ask |app| XHTML output by the *Input Plugin*, not on the input file itself. So, for example, if you ask calibre
to convert an RTF file to EPUB, it will first be converted to XHTML internally, to convert an RTF file to EPUB, it will first be converted to XHTML internally,
the various transforms will be applied to the XHTML and then the *Output Plugin* will the various transforms will be applied to the XHTML and then the *Output Plugin* will
create the EPUB file, automatically generating all metadata, Table of Contents, et cetera. create the EPUB file, automatically generating all metadata, Table of Contents, et cetera.
You can see this process in action by using the debug option |dbgi|. Just specify the path to You can see this process in action by using the debug option |dbgi|. Just specify the path to
a directory for the debug output. During conversion, |app| will place the XHTML generated by a directory for the debug output. During conversion, calibre will place the XHTML generated by
the various stages of the conversion pipeline in different sub-directories. the various stages of the conversion pipeline in different sub-directories.
The four sub-directories are: The four sub-directories are:
@ -78,7 +78,7 @@ The four sub-directories are:
processed Just before the ebook is passed to the output plugin. Use to debug the Output Plugin. processed Just before the ebook is passed to the output plugin. Use to debug the Output Plugin.
========== ============= ========== =============
If you want to edit the input document a little before having |app| convert it, the best thing to If you want to edit the input document a little before having calibre convert it, the best thing to
do is edit the files in the :file:`input` sub-directory, then zip it up, and use the zip file as the do is edit the files in the :file:`input` sub-directory, then zip it up, and use the zip file as the
input format for subsequent conversions. To do this use the :guilabel:`Edit meta information` dialog input format for subsequent conversions. To do this use the :guilabel:`Edit meta information` dialog
to add the zip file as a format for the book and then, in the top left corner of the conversion dialog, to add the zip file as a format for the book and then, in the top left corner of the conversion dialog,
@ -102,29 +102,29 @@ Font size rescaling
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
One of the nicest features of the e-reading experience is the ability to easily adjust font sizes to One of the nicest features of the e-reading experience is the ability to easily adjust font sizes to
suit individual needs and lighting conditions. |app| has sophisticated algorithms to ensure that suit individual needs and lighting conditions. calibre has sophisticated algorithms to ensure that
all the books it outputs have a consistent font sizes, no matter what font sizes are specified all the books it outputs have a consistent font sizes, no matter what font sizes are specified
in the input document. in the input document.
The base font size of a document is the most common font size in that document, The base font size of a document is the most common font size in that document,
i.e., the size of the bulk of text in that document. When you specify a i.e., the size of the bulk of text in that document. When you specify a
:guilabel:`Base font size`, |app| automatically rescales all font sizes in the document :guilabel:`Base font size`, calibre automatically rescales all font sizes in the document
proportionately, so that the most common font size becomes the specified base font size and other proportionately, so that the most common font size becomes the specified base font size and other
font sizes are rescaled appropriately. By choosing a larger base font size, you can make the fonts font sizes are rescaled appropriately. By choosing a larger base font size, you can make the fonts
in the document larger and vice versa. When you set the base font size, for best results, you should in the document larger and vice versa. When you set the base font size, for best results, you should
also set the font size key. also set the font size key.
Normally, |app| will automatically choose a base font size appropriate to the Output Profile you Normally, calibre will automatically choose a base font size appropriate to the Output Profile you
have chosen (see :ref:`page-setup`). However, you can override this here in case the default is have chosen (see :ref:`page-setup`). However, you can override this here in case the default is
not suitable for you. not suitable for you.
The :guilabel:`Font size key` option lets you control how non-base font sizes are rescaled. The :guilabel:`Font size key` option lets you control how non-base font sizes are rescaled.
The font rescaling algorithm works using a font size key, which is simply a comma-separated The font rescaling algorithm works using a font size key, which is simply a comma-separated
list of font sizes. The font size key tells |app| how many "steps" bigger or smaller a given font list of font sizes. The font size key tells calibre how many "steps" bigger or smaller a given font
size should be compared to the base font size. The idea is that there should be a limited number size should be compared to the base font size. The idea is that there should be a limited number
of font sizes in a document. For example, one size for the body text, a couple of sizes for of font sizes in a document. For example, one size for the body text, a couple of sizes for
different levels of headings and a couple of sizes for super/sub scripts and footnotes. The different levels of headings and a couple of sizes for super/sub scripts and footnotes. The
font size key allows |app| to compartmentalize the font sizes in the input documents into font size key allows calibre to compartmentalize the font sizes in the input documents into
separate "bins" corresponding to the different logical font sizes. separate "bins" corresponding to the different logical font sizes.
Let's illustrate with an example. Let's illustrate with an example.
@ -161,7 +161,7 @@ Paragraph spacing
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
Normally, paragraphs in XHTML are rendered with a blank line between them and no leading text Normally, paragraphs in XHTML are rendered with a blank line between them and no leading text
indent. |app| has a couple of options to control this. :guilabel:`Remove spacing between paragraphs` indent. calibre has a couple of options to control this. :guilabel:`Remove spacing between paragraphs`
forcefully ensure that all paragraphs have no inter paragraph spacing. It also sets the text forcefully ensure that all paragraphs have no inter paragraph spacing. It also sets the text
indent to 1.5em (can be changed) to mark the start of every paragraph. indent to 1.5em (can be changed) to mark the start of every paragraph.
:guilabel:`Insert blank line` does the :guilabel:`Insert blank line` does the
@ -209,7 +209,7 @@ Miscellaneous
There are a few more options in this section. There are a few more options in this section.
:guilabel:`No text justification` :guilabel:`No text justification`
Normally, if the output format supports it, |app| will force the output ebook Normally, if the output format supports it, calibre will force the output ebook
to have *justified* text (i.e., a smooth right margin). This option will turn to have *justified* text (i.e., a smooth right margin). This option will turn
off this behavior, in which case whatever justification is specified in the input document off this behavior, in which case whatever justification is specified in the input document
will be used instead. will be used instead.
@ -233,7 +233,7 @@ There are a few more options in this section.
:guilabel:`Input character encoding` :guilabel:`Input character encoding`
Older documents sometimes don't specify their character encoding. When converted, this can Older documents sometimes don't specify their character encoding. When converted, this can
result in non-English characters or special characters like smart quotes being corrupted. result in non-English characters or special characters like smart quotes being corrupted.
|app| tries to auto-detect the character encoding of the source document, but it does not' calibre tries to auto-detect the character encoding of the source document, but it does not'
always succeed. You can force it to assume a particular character encoding by using this setting. always succeed. You can force it to assume a particular character encoding by using this setting.
`cp1252` is a common encoding for documents produced using windows software. You should also read `cp1252` is a common encoding for documents produced using windows software. You should also read
:ref:`char-encoding-faq` for more on encoding issues. :ref:`char-encoding-faq` for more on encoding issues.
@ -268,27 +268,27 @@ option may lead to worse results, so use with care. As an example, several of t
remove all non-breaking-space entities, or may include false positive matches relating to the function. remove all non-breaking-space entities, or may include false positive matches relating to the function.
:guilabel:`Enable heuristic processing` :guilabel:`Enable heuristic processing`
This option activates |app|'s Heuristic Processing stage of the conversion pipeline. This option activates calibre's Heuristic Processing stage of the conversion pipeline.
This must be enabled in order for various sub-functions to be applied This must be enabled in order for various sub-functions to be applied
:guilabel:`Unwrap lines` :guilabel:`Unwrap lines`
Enabling this option will cause |app| to attempt to detect and correct hard line breaks that exist Enabling this option will cause calibre to attempt to detect and correct hard line breaks that exist
within a document using punctuation clues and line length. |app| will first attempt to detect whether within a document using punctuation clues and line length. calibre will first attempt to detect whether
hard line breaks exist, if they do not appear to exist |app| will not attempt to unwrap lines. The hard line breaks exist, if they do not appear to exist calibre will not attempt to unwrap lines. The
line-unwrap factor can be reduced if you want to 'force' |app| to unwrap lines. line-unwrap factor can be reduced if you want to 'force' calibre to unwrap lines.
:guilabel:`Line-unwrap factor` :guilabel:`Line-unwrap factor`
This option controls the algorithm |app| uses to remove hard line breaks. For example, if the value of this This option controls the algorithm calibre uses to remove hard line breaks. For example, if the value of this
option is 0.4, that means calibre will remove hard line breaks from the end of lines whose lengths are less option is 0.4, that means calibre will remove hard line breaks from the end of lines whose lengths are less
than the length of 40% of all lines in the document. If your document only has a few line breaks which need than the length of 40% of all lines in the document. If your document only has a few line breaks which need
correction, then this value should be reduced to somewhere between 0.1 and 0.2. correction, then this value should be reduced to somewhere between 0.1 and 0.2.
:guilabel:`Detect and markup unformatted chapter headings and sub headings` :guilabel:`Detect and markup unformatted chapter headings and sub headings`
If your document does not have chapter headings and titles formatted differently from the rest of the text, If your document does not have chapter headings and titles formatted differently from the rest of the text,
|app| can use this option to attempt detection them and surround them with heading tags. <h2> tags are used calibre can use this option to attempt detection them and surround them with heading tags. <h2> tags are used
for chapter headings; <h3> tags are used for any titles that are detected. for chapter headings; <h3> tags are used for any titles that are detected.
This function will not create a TOC, but in many cases it will cause |app|'s default chapter detection settings This function will not create a TOC, but in many cases it will cause calibre's default chapter detection settings
to correctly detect chapters and build a TOC. Adjust the XPath under Structure Detection if a TOC is not automatically to correctly detect chapters and build a TOC. Adjust the XPath under Structure Detection if a TOC is not automatically
created. If there are no other headings used in the document then setting "//h:h2" under Structure Detection would created. If there are no other headings used in the document then setting "//h:h2" under Structure Detection would
be the easiest way to create a TOC for the document. be the easiest way to create a TOC for the document.
@ -300,29 +300,29 @@ remove all non-breaking-space entities, or may include false positive matches re
:guilabel:`Renumber sequences of <h1> or <h2> tags` :guilabel:`Renumber sequences of <h1> or <h2> tags`
Some publishers format chapter headings using multiple <h1> or <h2> tags sequentially. Some publishers format chapter headings using multiple <h1> or <h2> tags sequentially.
|app|'s default conversion settings will cause such titles to be split into two pieces. This option calibre's default conversion settings will cause such titles to be split into two pieces. This option
will re-number the heading tags to prevent splitting. will re-number the heading tags to prevent splitting.
:guilabel:`Delete blank lines between paragraphs` :guilabel:`Delete blank lines between paragraphs`
This option will cause |app| to analyze blank lines included within the document. If every paragraph is interleaved This option will cause calibre to analyze blank lines included within the document. If every paragraph is interleaved
with a blank line, then |app| will remove all those blank paragraphs. Sequences of multiple blank lines will be with a blank line, then calibre will remove all those blank paragraphs. Sequences of multiple blank lines will be
considered scene breaks and retained as a single paragraph. This option differs from the 'Remove Paragraph Spacing' considered scene breaks and retained as a single paragraph. This option differs from the 'Remove Paragraph Spacing'
option under 'Look and Feel' in that it actually modifies the HTML content, while the other option modifies the document option under 'Look and Feel' in that it actually modifies the HTML content, while the other option modifies the document
styles. This option can also remove paragraphs which were inserted using |app|'s 'Insert blank line' option. styles. This option can also remove paragraphs which were inserted using calibre's 'Insert blank line' option.
:guilabel:`Ensure scene breaks are consistently formatted` :guilabel:`Ensure scene breaks are consistently formatted`
With this option |app| will attempt to detect common scene-break markers and ensure that they are center aligned. With this option calibre will attempt to detect common scene-break markers and ensure that they are center aligned.
'Soft' scene break markers, i.e. scene breaks only defined by extra white space, are styled to ensure that they 'Soft' scene break markers, i.e. scene breaks only defined by extra white space, are styled to ensure that they
will not be displayed in conjunction with page breaks. will not be displayed in conjunction with page breaks.
:guilabel:`Replace scene breaks` :guilabel:`Replace scene breaks`
If this option is configured then |app| will replace scene break markers it finds with the replacement text specified by the If this option is configured then calibre will replace scene break markers it finds with the replacement text specified by the
user. Please note that some ornamental characters may not be supported across all reading devices. user. Please note that some ornamental characters may not be supported across all reading devices.
In general you should avoid using html tags, |app| will discard any tags and use pre-defined markup. <hr /> In general you should avoid using html tags, calibre will discard any tags and use pre-defined markup. <hr />
tags, i.e. horizontal rules, and <img> tags are exceptions. Horizontal rules can optionally be specified with styles, if you tags, i.e. horizontal rules, and <img> tags are exceptions. Horizontal rules can optionally be specified with styles, if you
choose to add your own style be sure to include the 'width' setting, otherwise the style information will be discarded. Image choose to add your own style be sure to include the 'width' setting, otherwise the style information will be discarded. Image
tags can used, but |app| does not provide the ability to add the image during conversion, this must be done after the fact using tags can used, but calibre does not provide the ability to add the image during conversion, this must be done after the fact using
the 'Edit Book' feature. the 'Edit Book' feature.
Example image tag (place the image within an 'Images' folder inside the epub after conversion): Example image tag (place the image within an 'Images' folder inside the epub after conversion):
@ -332,19 +332,19 @@ remove all non-breaking-space entities, or may include false positive matches re
<hr style="width:20%;padding-top: 1px;border-top: 2px ridge black;border-bottom: 2px groove black;"/> <hr style="width:20%;padding-top: 1px;border-top: 2px ridge black;border-bottom: 2px groove black;"/>
:guilabel:`Remove unnecessary hyphens` :guilabel:`Remove unnecessary hyphens`
|app| will analyze all hyphenated content in the document when this option is enabled. The document itself is used calibre will analyze all hyphenated content in the document when this option is enabled. The document itself is used
as a dictionary for analysis. This allows |app| to accurately remove hyphens for any words in the document in any language, as a dictionary for analysis. This allows calibre to accurately remove hyphens for any words in the document in any language,
along with made-up and obscure scientific words. The primary drawback is words appearing only a single time in the document along with made-up and obscure scientific words. The primary drawback is words appearing only a single time in the document
will not be changed. Analysis happens in two passes, the first pass analyzes line endings. Lines are only unwrapped if the will not be changed. Analysis happens in two passes, the first pass analyzes line endings. Lines are only unwrapped if the
word exists with or without a hyphen in the document. The second pass analyzes all hyphenated words throughout the document, word exists with or without a hyphen in the document. The second pass analyzes all hyphenated words throughout the document,
hyphens are removed if the word exists elsewhere in the document without a match. hyphens are removed if the word exists elsewhere in the document without a match.
:guilabel:`Italicize common words and patterns` :guilabel:`Italicize common words and patterns`
When enabled, |app| will look for common words and patterns that denote italics and italicize them. Examples are common text When enabled, calibre will look for common words and patterns that denote italics and italicize them. Examples are common text
conventions such as ~word~ or phrases that should generally be italicized, e.g. latin phrases like 'etc.' or 'et cetera'. conventions such as ~word~ or phrases that should generally be italicized, e.g. latin phrases like 'etc.' or 'et cetera'.
:guilabel:`Replace entity indents with CSS indents` :guilabel:`Replace entity indents with CSS indents`
Some documents use a convention of defining text indents using non-breaking space entities. When this option is enabled |app| will Some documents use a convention of defining text indents using non-breaking space entities. When this option is enabled calibre will
attempt to detect this sort of formatting and convert them to a 3% text indent using css. attempt to detect this sort of formatting and convert them to a 3% text indent using css.
.. _search-replace: .. _search-replace:
@ -370,31 +370,31 @@ and their syntax at :ref:`regexptutorial`.
Structure Detection Structure Detection
--------------------- ---------------------
Structure detection involves |app| trying its best to detect structural elements in the input document, when they are not properly specified. For example, chapters, page breaks, headers, footers, etc. As you can imagine, this process varies widely from book to book. Fortunately, |app| has very powerful options to control this. With power comes complexity, but if once you take the time to learn the complexity, you will find it well worth the effort. Structure detection involves calibre trying its best to detect structural elements in the input document, when they are not properly specified. For example, chapters, page breaks, headers, footers, etc. As you can imagine, this process varies widely from book to book. Fortunately, calibre has very powerful options to control this. With power comes complexity, but if once you take the time to learn the complexity, you will find it well worth the effort.
Chapters and page breaks Chapters and page breaks
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| has two sets of options for :guilabel:`chapter detection` and :guilabel:`inserting page breaks`. This can sometimes be slightly confusing, as by default, calibre has two sets of options for :guilabel:`chapter detection` and :guilabel:`inserting page breaks`. This can sometimes be slightly confusing, as by default,
|app| will insert page breaks before detected chapters as well as the locations detected by the page breaks option. calibre will insert page breaks before detected chapters as well as the locations detected by the page breaks option.
The reason for this is that there are often location where page breaks should be inserted that are not chapter boundaries. The reason for this is that there are often location where page breaks should be inserted that are not chapter boundaries.
Also, detected chapters can be optionally inserted into the auto generated Table of Contents. Also, detected chapters can be optionally inserted into the auto generated Table of Contents.
|app| uses *XPath*, a powerful language to allow the user to specify chapter boundaries/page breaks. XPath can seem a little daunting calibre uses *XPath*, a powerful language to allow the user to specify chapter boundaries/page breaks. XPath can seem a little daunting
to use at first, fortunately, there is a :ref:`XPath tutorial <xpath-tutorial>` in the User Manual. Remember that Structure Detection to use at first, fortunately, there is a :ref:`XPath tutorial <xpath-tutorial>` in the User Manual. Remember that Structure Detection
operates on the intermediate XHTML produced by the conversion pipeline. Use the debug option described in the operates on the intermediate XHTML produced by the conversion pipeline. Use the debug option described in the
:ref:`conversion-introduction` to figure out the appropriate settings for your book. There is also a button for a XPath wizard :ref:`conversion-introduction` to figure out the appropriate settings for your book. There is also a button for a XPath wizard
to help with the generation of simple XPath expressions. to help with the generation of simple XPath expressions.
By default, |app| uses the following expression for chapter detection:: By default, calibre uses the following expression for chapter detection::
//*[((name()='h1' or name()='h2') and re:test(., 'chapter|book|section|part\s+', 'i')) or @class = 'chapter'] //*[((name()='h1' or name()='h2') and re:test(., 'chapter|book|section|part\s+', 'i')) or @class = 'chapter']
This expression is rather complex, because it tries to handle a number of common cases simulataneously. What it means This expression is rather complex, because it tries to handle a number of common cases simulataneously. What it means
is that |app| will assume chapters start at either `<h1>` or `<h2>` tags that have any of the words is that calibre will assume chapters start at either `<h1>` or `<h2>` tags that have any of the words
`(chapter, book, section or part)` in them or that have the `class="chapter"` attribute. `(chapter, book, section or part)` in them or that have the `class="chapter"` attribute.
A related option is :guilabel:`Chapter mark`, which allows you to control what |app| does when it detects a chapter. By default, A related option is :guilabel:`Chapter mark`, which allows you to control what calibre does when it detects a chapter. By default,
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. 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.
You can also have it do nothing. You can also have it do nothing.
@ -402,7 +402,7 @@ The default setting for detecting page breaks is::
//*[name()='h1' or name()='h2'] //*[name()='h1' or name()='h2']
which means that |app| will insert page breaks before every `<h1>` and `<h2>` tag by default. which means that calibre will insert page breaks before every `<h1>` and `<h2>` tag by default.
.. note:: .. note::
@ -414,22 +414,22 @@ Miscellaneous
There are a few more options in this section. There are a few more options in this section.
:guilabel:`Insert metadata as page at start of book` :guilabel:`Insert metadata as page at start of book`
One of the great things about |app| is that it allows you to maintain very complete metadata One of the great things about calibre is that it allows you to maintain very complete metadata
about all of your books, for example, a rating, tags, comments, etc. This option will create about all of your books, for example, a rating, tags, comments, etc. This option will create
a single page with all this metadata and insert it into the converted ebook, typically just a single page with all this metadata and insert it into the converted ebook, typically just
after the cover. Think of it as a way to create your own customised book jacket. after the cover. Think of it as a way to create your own customised book jacket.
:guilabel:`Remove first image` :guilabel:`Remove first image`
Sometimes, the source document you are converting includes the cover as part of the book, instead Sometimes, the source document you are converting includes the cover as part of the book, instead
of as a separate cover. If you also specify a cover in |app|, then the converted book will have of as a separate cover. If you also specify a cover in calibre, then the converted book will have
two covers. This option will simply remove the first image from the source document, thereby two covers. This option will simply remove the first image from the source document, thereby
ensuring that the converted book has only one cover, the one specified in |app|. ensuring that the converted book has only one cover, the one specified in calibre.
Table of Contents Table of Contents
------------------ ------------------
When the input document has a Table of Contents in its metadata, |app| will just use that. However, When the input document has a Table of Contents in its metadata, calibre will just use that. However,
a number of older formats either do not support a metadata based Table of Contents, or individual a number of older formats either do not support a metadata based Table of Contents, or individual
documents do not have one. In these cases, the options in this section can help you automatically documents do not have one. In these cases, the options in this section can help you automatically
generate a Table of Contents in the converted ebook, based on the actual content in the input document. generate a Table of Contents in the converted ebook, based on the actual content in the input document.
@ -447,21 +447,21 @@ generate a Table of Contents in the converted ebook, based on the actual content
want to edit and click the ToC Editor button. want to edit and click the ToC Editor button.
The first option is :guilabel:`Force use of auto-generated Table of Contents`. By checking this option The first option is :guilabel:`Force use of auto-generated Table of Contents`. By checking this option
you can have |app| override any Table of Contents found in the metadata of the input document with the you can have calibre override any Table of Contents found in the metadata of the input document with the
auto generated one. auto generated one.
The default way that the creation of the auto generated Table of Contents works is that, |app| will first try The default way that the creation of the auto generated Table of Contents works is that, calibre will first try
to add any detected chapters to the generated table of contents. You can learn how to customize the detection of chapters to add any detected chapters to the generated table of contents. You can learn how to customize the detection of chapters
in the :ref:`structure-detection` section above. If you do not want to include detected chapters in the generated in the :ref:`structure-detection` section above. If you do not want to include detected chapters in the generated
table of contents, check the :guilabel:`Do not add detected chapters` option. table of contents, check the :guilabel:`Do not add detected chapters` option.
If less than the :guilabel:`Chapter threshold` number of chapters were detected, |app| will then add any hyperlinks If less than the :guilabel:`Chapter threshold` number of chapters were detected, calibre will then add any hyperlinks
it finds in the input document to the Table of Contents. This often works well many input documents include a it finds in the input document to the Table of Contents. This often works well many input documents include a
hyperlinked Table of Contents right at the start. The :guilabel:`Number of links` option can be used to control hyperlinked Table of Contents right at the start. The :guilabel:`Number of links` option can be used to control
this behavior. If set to zero, no links are added. If set to a number greater than zero, at most that number of links this behavior. If set to zero, no links are added. If set to a number greater than zero, at most that number of links
is added. is added.
|app| will automatically filter duplicates from the generated Table of Contents. However, if there are some additional calibre will automatically filter duplicates from the generated Table of Contents. However, if there are some additional
undesirable entries, you can filter them using the :guilabel:`TOC Filter` option. This is a regular expression that undesirable entries, you can filter them using the :guilabel:`TOC Filter` option. This is a regular expression that
will match the title of entries in the generated table of contents. Whenever a match is found, it will be removed. will match the title of entries in the generated table of contents. Whenever a match is found, it will be removed.
For example, to remove all entries titles "Next" or "Previous" use:: For example, to remove all entries titles "Next" or "Previous" use::
@ -518,7 +518,7 @@ This will result in an automatically generated two level Table of Contents that
Using images as chapter titles when converting HTML input documents Using images as chapter titles when converting HTML input documents
--------------------------------------------------------------------- ---------------------------------------------------------------------
Suppose you want to use an image as your chapter title, but still want |app| to be able to automatically generate a Table of Contents for you from the chapter titles. 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.
Use the following HTML markup to achieve this Use the following HTML markup to achieve this
.. code-block:: html .. code-block:: html
@ -532,7 +532,7 @@ Use the following HTML markup to achieve this
</body> </body>
</html> </html>
Set the :guilabel:`Level 1 TOC` setting to ``//h:h2``. Then, for chapter two, |app| will take the title from the value of the ``title`` attribute on the ``<h2>`` tag, since the tag has no text. 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.
Using tag attributes to supply the text for entries in the Table of Contents Using tag attributes to supply the text for entries in the Table of Contents
----------------------------------------------------------------------------- -----------------------------------------------------------------------------
@ -552,22 +552,22 @@ example:
</body> </body>
</html> </html>
Set the :guilabel:`Level 1 TOC` setting to ``//h:h2/@title``. Then |app| will Set the :guilabel:`Level 1 TOC` setting to ``//h:h2/@title``. Then calibre will
take the title from the value of the ``title`` attribute on the ``<h2>`` tags, take the title from the value of the ``title`` attribute on the ``<h2>`` tags,
instead of using the text inside the tag. Note the trailing ``/@title`` on the instead of using the text inside the tag. Note the trailing ``/@title`` on the
XPath expression, you can use this form to tell |app| to get the text from any XPath expression, you can use this form to tell calibre to get the text from any
attribute you like. attribute you like.
How options are set/saved for Conversion How options are set/saved for Conversion
------------------------------------------- -------------------------------------------
There are two places where conversion options can be set in |app|. The first is There are two places where conversion options can be set in calibre. The first is
in Preferences->Conversion. These settings are the defaults for the conversion in Preferences->Conversion. These settings are the defaults for the conversion
options. Whenever you try to convert a new book, the settings set here will be options. Whenever you try to convert a new book, the settings set here will be
used by default. used by default.
You can also change settings in the conversion dialog for each book conversion. You can also change settings in the conversion dialog for each book conversion.
When you convert a book, |app| remembers the settings you used for that book, When you convert a book, calibre remembers the settings you used for that book,
so that if you convert it again, the saved settings for the individual book so that if you convert it again, the saved settings for the individual book
will take precedence over the defaults set in Preferences. You can restore the will take precedence over the defaults set in Preferences. You can restore the
individual settings to defaults by using the Restore to defaults button in the individual settings to defaults by using the Restore to defaults button in the
@ -611,16 +611,16 @@ format, whether input or output are available in the conversion dialog under the
Convert Microsoft Word documents Convert Microsoft Word documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| can automatically convert ``.docx`` files created by Microsoft Word 2007 and calibre can automatically convert ``.docx`` files created by Microsoft Word 2007 and
newer. Just add the file to |app| and click convert (make sure you are running newer. Just add the file to calibre and click convert (make sure you are running
the latest version of |app| as support for ``.docx`` files is very new). the latest version of calibre as support for ``.docx`` files is very new).
.. note:: .. note::
There is a `demo .docx file <http://calibre-ebook.com/downloads/demos/demo.docx>`_ There is a `demo .docx file <http://calibre-ebook.com/downloads/demos/demo.docx>`_
that demonstrates the capabilities of the |app| conversion engine. Just that demonstrates the capabilities of the calibre conversion engine. Just
download it and convert it to EPUB or AZW3 to see what |app| can do. download it and convert it to EPUB or AZW3 to see what calibre can do.
|app| will automatically generate a Table of Contents based on headings if you mark calibre will automatically generate a Table of Contents based on headings if you mark
your headings with the ``Heading 1``, ``Heading 2``, etc. styles in Word. Open your headings with the ``Heading 1``, ``Heading 2``, etc. styles in Word. Open
the output ebook in the calibre viewer and click the Table of Contents button the output ebook in the calibre viewer and click the Table of Contents button
to view the generated Table of Contents. to view the generated Table of Contents.
@ -629,14 +629,14 @@ Older .doc files
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
For older .doc files, you can save the document as HTML with Microsoft Word For older .doc files, you can save the document as HTML with Microsoft Word
and then convert the resulting HTML file with |app|. When saving as and then convert the resulting HTML file with calibre. When saving as
HTML, be sure to use the "Save as Web Page, Filtered" option as this will HTML, be sure to use the "Save as Web Page, Filtered" option as this will
produce clean HTML that will convert well. Note that Word produces really messy produce clean HTML that will convert well. Note that Word produces really messy
HTML, converting it can take a long time, so be patient. If you have a newer HTML, converting it can take a long time, so be patient. If you have a newer
version of Word available, you can directly save it as docx as well. version of Word available, you can directly save it as docx as well.
Another alternative is to use the free OpenOffice. Open your .doc file in Another alternative is to use the free OpenOffice. Open your .doc file in
OpenOffice and save it in OpenOffice's format .odt. |app| can directly convert OpenOffice and save it in OpenOffice's format .odt. calibre can directly convert
.odt files. .odt files.
Convert TXT documents Convert TXT documents
@ -644,7 +644,7 @@ Convert TXT documents
TXT documents have no well defined way to specify formatting like bold, italics, etc, or document TXT documents have no well defined way to specify formatting like bold, italics, etc, or document
structure like paragraphs, headings, sections and so on, but there are a variety of conventions commonly structure like paragraphs, headings, sections and so on, but there are a variety of conventions commonly
used. By default |app| attempts automatic detection of the correct formatting and markup based on those used. By default calibre attempts automatic detection of the correct formatting and markup based on those
conventions. conventions.
TXT input supports a number of options to differentiate how paragraphs are detected. TXT input supports a number of options to differentiate how paragraphs are detected.
@ -692,7 +692,7 @@ TXT input supports a number of options to differentiate how paragraphs are detec
appropriate html markup during conversion. appropriate html markup during conversion.
:guilabel:`Formatting Style: Markdown` :guilabel:`Formatting Style: Markdown`
|app| also supports running TXT input though a transformation preprocessor known as markdown. Markdown calibre also supports running TXT input though a transformation preprocessor known as markdown. Markdown
allows for basic formatting to be added to TXT documents, such as bold, italics, section headings, tables, allows for basic formatting to be added to TXT documents, such as bold, italics, section headings, tables,
lists, a Table of Contents, etc. Marking chapter headings with a leading # and setting the chapter XPath detection lists, a Table of Contents, etc. Marking chapter headings with a leading # and setting the chapter XPath detection
expression to "//h:h1" is the easiest way to have a proper table of contents generated from a TXT document. expression to "//h:h1" is the easiest way to have a proper table of contents generated from a TXT document.
@ -707,7 +707,7 @@ Convert PDF documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
PDF documents are one of the worst formats to convert from. They are a fixed page size and text placement format. PDF documents are one of the worst formats to convert from. They are a fixed page size and text placement format.
Meaning, it is very difficult to determine where one paragraph ends and another begins. |app| will try to unwrap Meaning, it is very difficult to determine where one paragraph ends and another begins. calibre will try to unwrap
paragraphs using a configurable, :guilabel:`Line Un-Wrapping Factor`. This is a scale used to determine the length paragraphs using a configurable, :guilabel:`Line Un-Wrapping Factor`. This is a scale used to determine the length
at which a line should be unwrapped. Valid values are a decimal at which a line should be unwrapped. Valid values are a decimal
between 0 and 1. The default is 0.45, just under the median line length. Lower this value to include more between 0 and 1. The default is 0.45, just under the median line length. Lower this value to include more
@ -725,7 +725,7 @@ Some limitations of PDF input are:
* 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. * 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.
* Links and Tables of Contents are not supported * Links and Tables of Contents are not supported
* PDFs that use embedded non-unicode fonts to represent non-English characters will result in garbled output for those characters * PDFs that use embedded non-unicode fonts to represent non-English characters will result in garbled output for those characters
* Some PDFs are made up of photographs of the page with OCRed text behind them. In such cases |app| uses the OCRed text, which can be very different from what you see when you view the PDF file * 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
* PDFs that are used to display complex text, like right to left languages and math typesetting will not convert correctly * PDFs that are used to display complex text, like right to left languages and math typesetting will not convert correctly
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 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
@ -749,7 +749,7 @@ The .cbc file will then contain::
two.cbz two.cbz
three.cbz three.cbz
|app| will automatically convert this .cbc file into a ebook with a Table of Contents pointing to each entry in comics.txt. calibre will automatically convert this .cbc file into a ebook with a Table of Contents pointing to each entry in comics.txt.
EPUB advanced formatting demo EPUB advanced formatting demo
@ -763,24 +763,24 @@ EPUB from the ZIP file are::
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 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
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 |app|'s built-in EPUB viewer. 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.
Convert ODT documents Convert ODT documents
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
|app| can directly convert ODT (OpenDocument Text) files. You should use styles to format your document and minimize the use of direct formatting. calibre can directly convert ODT (OpenDocument Text) files. You should use styles to format your document and minimize the use of direct formatting.
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. 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.
To enable automatic detection of chapters, you need to mark them with the build-in styles called 'Heading 1', 'Heading 2', ..., 'Heading 6' ('Heading 1' equates to the HTML tag <h1>, 'Heading 2' to <h2> etc). When you convert in |app| you can enter which style you used into the 'Detect chapters at' box. Example: To enable automatic detection of chapters, you need to mark them with the build-in styles called 'Heading 1', 'Heading 2', ..., 'Heading 6' ('Heading 1' equates to the HTML tag <h1>, 'Heading 2' to <h2> etc). When you convert in calibre you can enter which style you used into the 'Detect chapters at' box. Example:
* If you mark Chapters with style 'Heading 2', you have to set the 'Detect chapters at' box to ``//h:h2`` * If you mark Chapters with style 'Heading 2', you have to set the 'Detect chapters at' box to ``//h:h2``
* For a nested TOC with Sections marked with 'Heading 2' and the Chapters marked with 'Heading 3' you need to enter ``//h:h2|//h:h3``. On the Convert - TOC page set the 'Level 1 TOC' box to ``//h:h2`` and the 'Level 2 TOC' box to ``//h:h3``. * For a nested TOC with Sections marked with 'Heading 2' and the Chapters marked with 'Heading 3' you need to enter ``//h:h2|//h:h3``. On the Convert - TOC page set the 'Level 1 TOC' box to ``//h:h2`` and the 'Level 2 TOC' box to ``//h:h3``.
Well-known document properties (Title, Keywords, Description, Creator) are recognized and |app| will use the first image (not to small, and with good aspect-ratio) as the cover image. Well-known document properties (Title, Keywords, Description, Creator) are recognized and calibre will use the first image (not to small, and with good aspect-ratio) as the cover image.
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). 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).
If this property is detected by |app|, the following custom properties are recognized (``opf.authors`` overrides document creator):: If this property is detected by calibre, the following custom properties are recognized (``opf.authors`` overrides document creator)::
opf.titlesort opf.titlesort
opf.authors opf.authors
@ -805,8 +805,8 @@ Converting to PDF
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
The first, most important, setting to decide on when converting to PDF is the page The first, most important, setting to decide on when converting to PDF is the page
size. By default, |app| uses a page size defined by the current size. By default, calibre uses a page size defined by the current
:guilabel:`Output profile`. So if your output profile is set to Kindle, |app| :guilabel:`Output profile`. So if your output profile is set to Kindle, calibre
will create a PDF with page size suitable for viewing on the small kindle will create a PDF with page size suitable for viewing on the small kindle
screen. However, if you view this PDF file on a computer screen, then it will screen. However, if you view this PDF file on a computer screen, then it will
appear to have too large fonts. To create "normal" sized PDFs, use the appear to have too large fonts. To create "normal" sized PDFs, use the
@ -822,13 +822,13 @@ footer template::
<p style="text-align:center; color:green">Page _PAGENUM_</p> <p style="text-align:center; color:green">Page _PAGENUM_</p>
|app| will automatically replace _PAGENUM_ with the current page number. You calibre will automatically replace _PAGENUM_ with the current page number. You
can even put different content on even and odd pages, for example the following can even put different content on even and odd pages, for example the following
header template will show the title on odd pages and the author on even pages:: header template will show the title on odd pages and the author on even pages::
<p style="text-align:right"><span class="even_page">_AUTHOR_</span><span class="odd_page"><i>_TITLE_</i></span></p> <p style="text-align:right"><span class="even_page">_AUTHOR_</span><span class="odd_page"><i>_TITLE_</i></span></p>
|app| will automatically replace _TITLE_ and _AUTHOR_ with the title and author calibre will automatically replace _TITLE_ and _AUTHOR_ with the title and author
of the document being converted. You can also display text at the left and of the document being converted. You can also display text at the left and
right edges and change the font size, as demonstrated with this header right edges and change the font size, as demonstrated with this header
template:: template::

50
manual/creating_plugins.rst
View File

@ -1,11 +1,11 @@
.. _pluginstutorial: .. _pluginstutorial:
Writing your own plugins to extend |app|'s functionality Writing your own plugins to extend calibre's functionality
==================================================================== ====================================================================
|app| has a very modular design. Almost all functionality in |app| comes in the form of plugins. Plugins are used for conversion, for downloading news (though these are called recipes), for various components of the user interface, to connect to different devices, to process files when adding them to |app| and so on. You can get a complete list of all the built-in plugins in |app| by going to :guilabel:`Preferences->Plugins`. calibre has a very modular design. Almost all functionality in calibre comes in the form of plugins. Plugins are used for conversion, for downloading news (though these are called recipes), for various components of the user interface, to connect to different devices, to process files when adding them to calibre and so on. You can get a complete list of all the built-in plugins in calibre by going to :guilabel:`Preferences->Plugins`.
Here, we will teach you how to create your own plugins to add new features to |app|. Here, we will teach you how to create your own plugins to add new features to calibre.
.. contents:: Contents .. contents:: Contents
@ -14,28 +14,28 @@ Here, we will teach you how to create your own plugins to add new features to |a
.. note:: This only applies to calibre releases >= 0.8.60 .. note:: This only applies to calibre releases >= 0.8.60
Anatomy of a |app| plugin Anatomy of a calibre plugin
--------------------------- ---------------------------
A |app| plugin is very simple, it's just a zip file that contains some python code A calibre plugin is very simple, it's just a zip file that contains some python code
and any other resources like image files needed by the plugin. Without further ado, and any other resources like image files needed by the plugin. Without further ado,
let's see a basic example. let's see a basic example.
Suppose you have an installation of |app| that you are using to self publish various e-documents in EPUB and MOBI Suppose you have an installation of calibre that you are using to self publish various e-documents in EPUB and MOBI
formats. You would like all files generated by |app| to have their publisher set as "Hello world", here's how to do it. formats. You would like all files generated by calibre to have their publisher set as "Hello world", here's how to do it.
Create a file named :file:`__init__.py` (this is a special name and must always be used for the main file of your plugin) Create a file named :file:`__init__.py` (this is a special name and must always be used for the main file of your plugin)
and enter the following Python code into it: and enter the following Python code into it:
.. literalinclude:: plugin_examples/helloworld/__init__.py .. literalinclude:: plugin_examples/helloworld/__init__.py
:lines: 10- :lines: 10-
That's all. To add this code to |app| as a plugin, simply run the following in That's all. To add this code to calibre as a plugin, simply run the following in
the directory in which you created :file:`__init__.py`:: the directory in which you created :file:`__init__.py`::
calibre-customize -b . calibre-customize -b .
.. note:: .. note::
On OS X, the command line tools are inside the |app| bundle, for example, On OS X, the command line tools are inside the calibre bundle, for example,
if you installed calibre in :file:`/Applications` the command line tools if you installed calibre in :file:`/Applications` the command line tools
are in :file:`/Applications/calibre.app/Contents/console.app/Contents/MacOS/`. are in :file:`/Applications/calibre.app/Contents/console.app/Contents/MacOS/`.
@ -51,8 +51,8 @@ A User Interface plugin
This plugin will be spread over a few files (to keep the code clean). It will show you how to get resources This plugin will be spread over a few files (to keep the code clean). It will show you how to get resources
(images or data files) from the plugin zip file, allow users to configure your plugin, (images or data files) from the plugin zip file, allow users to configure your plugin,
how to create elements in the |app| user interface and how to access how to create elements in the calibre user interface and how to access
and query the books database in |app|. and query the books database in calibre.
You can download this plugin from `interface_demo_plugin.zip <http://calibre-ebook.com/downloads/interface_demo_plugin.zip>`_ You can download this plugin from `interface_demo_plugin.zip <http://calibre-ebook.com/downloads/interface_demo_plugin.zip>`_
@ -106,9 +106,9 @@ First, the obligatory ``__init__.py`` to define the plugin metadata:
.. literalinclude:: plugin_examples/interface_demo/__init__.py .. literalinclude:: plugin_examples/interface_demo/__init__.py
:lines: 10- :lines: 10-
The only noteworthy feature is the field :attr:`actual_plugin`. Since |app| has both command line and GUI interfaces, The only noteworthy feature is the field :attr:`actual_plugin`. Since calibre has both command line and GUI interfaces,
GUI plugins like this one should not load any GUI libraries in __init__.py. The actual_plugin field does this for you, GUI plugins like this one should not load any GUI libraries in __init__.py. The actual_plugin field does this for you,
by telling |app| that the actual plugin is to be found in another file inside your zip archive, which will only be loaded by telling calibre that the actual plugin is to be found in another file inside your zip archive, which will only be loaded
in a GUI context. in a GUI context.
Remember that for this to work, you must have a plugin-import-name-some_name.txt file in your plugin zip file, Remember that for this to work, you must have a plugin-import-name-some_name.txt file in your plugin zip file,
@ -135,7 +135,7 @@ The actual logic to implement the Interface Plugin Demo dialog.
Getting resources from the plugin zip file Getting resources from the plugin zip file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|app|'s plugin loading system defines a couple of built-in functions that allow you to conveniently get files from the plugin zip file. calibre's plugin loading system defines a couple of built-in functions that allow you to conveniently get files from the plugin zip file.
**get_resources(name_or_list_of_names)** **get_resources(name_or_list_of_names)**
This function should be called with a list of paths to files inside the zip file. For example to access the file icon.png in This function should be called with a list of paths to files inside the zip file. For example to access the file icon.png in
@ -162,7 +162,7 @@ To allow users to configure your plugin, you must define three methods in your b
.. literalinclude:: plugin_examples/interface_demo/__init__.py .. literalinclude:: plugin_examples/interface_demo/__init__.py
:pyobject: InterfacePluginDemo.save_settings :pyobject: InterfacePluginDemo.save_settings
|app| has many different ways to store configuration data (a legacy of its long history). The recommended way is to use the **JSONConfig** class, which stores your configuration information in a .json file. calibre has many different ways to store configuration data (a legacy of its long history). The recommended way is to use the **JSONConfig** class, which stores your configuration information in a .json file.
The code to manage configuration data in the demo plugin is in config.py: The code to manage configuration data in the demo plugin is in config.py:
@ -184,7 +184,7 @@ Edit Book plugins
------------------------------------------ ------------------------------------------
Now let's change gears for a bit and look at creating a plugin to add tools to Now let's change gears for a bit and look at creating a plugin to add tools to
the |app| book editor. The plugin is available here: the calibre book editor. The plugin is available here:
`editor_demo_plugin.zip <http://calibre-ebook.com/downloads/editor_demo_plugin.zip>`_. `editor_demo_plugin.zip <http://calibre-ebook.com/downloads/editor_demo_plugin.zip>`_.
The first step, as for all plugins is to create the The first step, as for all plugins is to create the
@ -288,41 +288,41 @@ Replace ``de`` with the language code of the language you want to test.
The plugin API The plugin API
-------------------------------- --------------------------------
As you may have noticed above, a plugin in |app| is a class. There are different classes for the different types of plugins in |app|. As you may have noticed above, a plugin in calibre is a class. There are different classes for the different types of plugins in calibre.
Details on each class, including the base class of all plugins can be found in :ref:`plugins`. Details on each class, including the base class of all plugins can be found in :ref:`plugins`.
Your plugin is almost certainly going to use code from |app|. To learn Your plugin is almost certainly going to use code from calibre. To learn
how to find various bits of functionality in the how to find various bits of functionality in the
|app| code base, read the section on the |app| :ref:`code_layout`. calibre code base, read the section on the calibre :ref:`code_layout`.
Debugging plugins Debugging plugins
------------------- -------------------
The first, most important step is to run |app| in debug mode. You can do this from the command line with:: The first, most important step is to run calibre in debug mode. You can do this from the command line with::
calibre-debug -g calibre-debug -g
Or from within calibre by right-clicking the preferences button or using the `Ctrl+Shift+R` keyboard shortcut. Or from within calibre by right-clicking the preferences button or using the `Ctrl+Shift+R` keyboard shortcut.
When running from the command line, debug output will be printed to the console, when running from within |app| the output will go to a txt file. When running from the command line, debug output will be printed to the console, when running from within calibre the output will go to a txt file.
You can insert print statements anywhere in your plugin code, they will be output in debug mode. Remember, this is python, you really shouldn't need anything more than print statements to debug ;) I developed all of |app| using just this debugging technique. You can insert print statements anywhere in your plugin code, they will be output in debug mode. Remember, this is python, you really shouldn't need anything more than print statements to debug ;) I developed all of calibre using just this debugging technique.
You can quickly test changes to your plugin by using the following command You can quickly test changes to your plugin by using the following command
line:: line::
calibre-debug -s; calibre-customize -b /path/to/your/plugin/directory; calibre calibre-debug -s; calibre-customize -b /path/to/your/plugin/directory; calibre
This will shutdown a running calibre, wait for the shutdown to complete, then update your plugin in |app| and relaunch |app|. This will shutdown a running calibre, wait for the shutdown to complete, then update your plugin in calibre and relaunch calibre.
More plugin examples More plugin examples
---------------------- ----------------------
You can find a list of many, sophisticated |app| plugins `here <http://www.mobileread.com/forums/showthread.php?t=118764>`_. You can find a list of many, sophisticated calibre plugins `here <http://www.mobileread.com/forums/showthread.php?t=118764>`_.
Sharing your plugins with others Sharing your plugins with others
---------------------------------- ----------------------------------
If you would like to share the plugins you have created with other users of |app|, post your plugin in a new thread in the If you would like to share the plugins you have created with other users of calibre, post your plugin in a new thread in the
`calibre plugins forum <http://www.mobileread.com/forums/forumdisplay.php?f=237>`_. `calibre plugins forum <http://www.mobileread.com/forums/forumdisplay.php?f=237>`_.

6
manual/custom.py
View File

@ -10,7 +10,6 @@ del init_calibre
from sphinx.util.console import bold from sphinx.util.console import bold
sys.path.append(os.path.abspath('../../../')) sys.path.append(os.path.abspath('../../../'))
from calibre import __appname__
from calibre.linux import entry_points, cli_index_strings from calibre.linux import entry_points, cli_index_strings
from epub import EPUBHelpBuilder from epub import EPUBHelpBuilder
from latex import LaTeXHelpBuilder from latex import LaTeXHelpBuilder
@ -23,7 +22,6 @@ include_pat = re.compile(r'^.. include:: (\S+.rst)', re.M)
def source_read_handler(app, docname, source): def source_read_handler(app, docname, source):
src = source[0] src = source[0]
src = src.replace('|lang|', app.config.language) src = src.replace('|lang|', app.config.language)
src = src.replace('|app|', __appname__)
# Sphinx does not call source_read_handle for the .. include directive # Sphinx does not call source_read_handle for the .. include directive
for m in reversed(tuple(include_pat.finditer(src))): for m in reversed(tuple(include_pat.finditer(src))):
ss = [open(m.group(1)).read().decode('utf-8')] ss = [open(m.group(1)).read().decode('utf-8')]
@ -35,7 +33,7 @@ CLI_INDEX='''
.. _cli: .. _cli:
%s %s
========================== =========================================================
.. image:: ../../images/cli.png .. image:: ../../images/cli.png
@ -77,7 +75,7 @@ def generate_calibredb_help(preamble, app):
preamble = preamble[:preamble.find('\n\n\n', preamble.find('code-block'))] preamble = preamble[:preamble.find('\n\n\n', preamble.find('code-block'))]
preamble += textwrap.dedent(''' preamble += textwrap.dedent('''
:command:`calibredb` is the command line interface to the |app| database. It has :command:`calibredb` is the command line interface to the calibre database. It has
several sub-commands, documented below: several sub-commands, documented below:
''') ''')

26
manual/customize.rst
View File

@ -2,14 +2,14 @@
.. _customize: .. _customize:
Customizing |app| Customizing calibre
================================== ==================================
|app| has a highly modular design. Various parts of it can be customized. You can learn how to create calibre has a highly modular design. Various parts of it can be customized. You can learn how to create
*recipes* to add new sources of online content to |app| in the Section :ref:`news`. Here, you will learn, *recipes* to add new sources of online content to calibre in the Section :ref:`news`. Here, you will learn,
first, how to use environment variables and *tweaks* to customize |app|'s behavior, and then how to first, how to use environment variables and *tweaks* to customize calibre's behavior, and then how to
specify your own static resources like icons and templates to override the defaults and finally how to specify your own static resources like icons and templates to override the defaults and finally how to
use *plugins* to add functionality to |app|. use *plugins* to add functionality to calibre.
.. contents:: .. contents::
:depth: 2 :depth: 2
@ -38,7 +38,7 @@ See `How to set environment variables in windows <http://www.computerhope.com/is
Tweaks Tweaks
------------ ------------
Tweaks are small changes that you can specify to control various aspects of |app|'s behavior. You can change them by going to Preferences->Advanced->Tweaks. Tweaks are small changes that you can specify to control various aspects of calibre's behavior. You can change them by going to Preferences->Advanced->Tweaks.
The default values for the tweaks are reproduced below The default values for the tweaks are reproduced below
.. literalinclude:: ../resources/default_tweaks.py .. literalinclude:: ../resources/default_tweaks.py
@ -47,22 +47,22 @@ The default values for the tweaks are reproduced below
Overriding icons, templates, et cetera Overriding icons, templates, et cetera
---------------------------------------- ----------------------------------------
|app| allows you to override the static resources, like icons, javascript and calibre allows you to override the static resources, like icons, javascript and
templates for the metadata jacket, catalogs, etc. with customized versions that templates for the metadata jacket, catalogs, etc. with customized versions that
you like. All static resources are stored in the resources sub-folder of the you like. All static resources are stored in the resources sub-folder of the
calibre install location. On Windows, this is usually :file:`C:/Program Files/Calibre2/resources`. calibre install location. On Windows, this is usually :file:`C:/Program Files/Calibre2/resources`.
On OS X, :file:`/Applications/calibre.app/Contents/Resources/resources/`. On linux, if On OS X, :file:`/Applications/calibre.app/Contents/Resources/resources/`. On linux, if
you are using the binary installer from the calibre website it will be you are using the binary installer from the calibre website it will be
:file:`/opt/calibre/resources`. These paths can change depending on where you :file:`/opt/calibre/resources`. These paths can change depending on where you
choose to install |app|. choose to install calibre.
You should not change the files in this resources folder, as your changes will You should not change the files in this resources folder, as your changes will
get overwritten the next time you update |app|. Instead, go to get overwritten the next time you update calibre. Instead, go to
:guilabel:`Preferences->Advanced->Miscellaneous` and click :guilabel:`Preferences->Advanced->Miscellaneous` and click
:guilabel:`Open calibre configuration directory`. In this configuration directory, create a :guilabel:`Open calibre configuration directory`. In this configuration directory, create a
sub-folder called resources and place the files you want to override in it. sub-folder called resources and place the files you want to override in it.
Place the files in the appropriate sub folders, for example place images in Place the files in the appropriate sub folders, for example place images in
:file:`resources/images`, etc. |app| will automatically use your custom file :file:`resources/images`, etc. calibre will automatically use your custom file
in preference to the built-in one the next time it is started. in preference to the built-in one the next time it is started.
For example, if you wanted to change the icon for the :guilabel:`Remove books` For example, if you wanted to change the icon for the :guilabel:`Remove books`
@ -73,10 +73,10 @@ the configuration directory as :file:`resources/images/trash.png`. All the
icons used by the calibre user interface are in :file:`resources/images` and icons used by the calibre user interface are in :file:`resources/images` and
its sub-folders. its sub-folders.
Customizing |app| with plugins Customizing calibre with plugins
-------------------------------- --------------------------------
|app| has a very modular design. Almost all functionality in |app| comes in the form of plugins. Plugins are used for conversion, for downloading news (though these are called recipes), for various components of the user interface, to connect to different devices, to process files when adding them to |app| and so on. You can get a complete list of all the built-in plugins in |app| by going to :guilabel:`Preferences->Plugins`. calibre has a very modular design. Almost all functionality in calibre comes in the form of plugins. Plugins are used for conversion, for downloading news (though these are called recipes), for various components of the user interface, to connect to different devices, to process files when adding them to calibre and so on. You can get a complete list of all the built-in plugins in calibre by going to :guilabel:`Preferences->Plugins`.
You can write your own plugins to customize and extend the behavior of |app|. The plugin architecture in |app| is very simple, see the tutorial :ref:`pluginstutorial`. You can write your own plugins to customize and extend the behavior of calibre. The plugin architecture in calibre is very simple, see the tutorial :ref:`pluginstutorial`.

128
manual/develop.rst
View File

@ -1,13 +1,13 @@
.. _develop: .. _develop:
Setting up a |app| development environment Setting up a calibre development environment
=========================================================== ===========================================================
|app| is completely open source, licensed under the `GNU GPL v3 <http://www.gnu.org/copyleft/gpl.html>`_. calibre is completely open source, licensed under the `GNU GPL v3 <http://www.gnu.org/copyleft/gpl.html>`_.
This means that you are free to download and modify the program to your heart's content. In this section, This means that you are free to download and modify the program to your heart's content. In this section,
you will learn how to get a |app| development environment set up on the operating system of your choice. you will learn how to get a calibre development environment set up on the operating system of your choice.
|app| is written primarily in `Python <http://www.python.org>`_ with some C/C++ code for speed and system interfacing. calibre is written primarily in `Python <http://www.python.org>`_ with some C/C++ code for speed and system interfacing.
Note that |app| is not compatible with Python 3 and requires at least Python 2.7. Note that calibre is not compatible with Python 3 and requires at least Python 2.7.
.. contents:: Contents .. contents:: Contents
:depth: 2 :depth: 2
@ -16,29 +16,29 @@ Note that |app| is not compatible with Python 3 and requires at least Python 2.7
Design philosophy Design philosophy
------------------- -------------------
|app| has its roots in the Unix world, which means that its design is highly modular. calibre has its roots in the Unix world, which means that its design is highly modular.
The modules interact with each other via well defined interfaces. This makes adding new features and fixing The modules interact with each other via well defined interfaces. This makes adding new features and fixing
bugs in |app| very easy, resulting in a frenetic pace of development. Because of its roots, |app| has a bugs in calibre very easy, resulting in a frenetic pace of development. Because of its roots, calibre has a
comprehensive command line interface for all its functions, documented in :doc:`generated/|lang|/cli-index`. comprehensive command line interface for all its functions, documented in :doc:`generated/|lang|/cli-index`.
The modular design of |app| is expressed via ``Plugins``. There is a :ref:`tutorial <customize>` on writing |app| plugins. The modular design of calibre is expressed via ``Plugins``. There is a :ref:`tutorial <customize>` on writing calibre plugins.
For example, adding support for a new device to |app| typically involves writing less than a 100 lines of code in the form of For example, adding support for a new device to calibre typically involves writing less than a 100 lines of code in the form of
a device driver plugin. You can browse the a device driver plugin. You can browse the
`built-in drivers <http://bazaar.launchpad.net/%7Ekovid/calibre/trunk/files/head%3A/src/calibre/devices/>`_. Similarly, adding support `built-in drivers <http://bazaar.launchpad.net/%7Ekovid/calibre/trunk/files/head%3A/src/calibre/devices/>`_. Similarly, adding support
for new conversion formats involves writing input/output format plugins. Another example of the modular design is the :ref:`recipe system <news>` for for new conversion formats involves writing input/output format plugins. Another example of the modular design is the :ref:`recipe system <news>` for
fetching news. For more examples of plugins designed to add features to |app|, see the `plugin index <http://www.mobileread.com/forums/showthread.php?p=1362767#post1362767>`_. fetching news. For more examples of plugins designed to add features to calibre, see the `plugin index <http://www.mobileread.com/forums/showthread.php?p=1362767#post1362767>`_.
.. _code_layout: .. _code_layout:
Code layout Code layout
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
All the |app| python code is in the ``calibre`` package. This package contains the following main sub-packages All the calibre python code is in the ``calibre`` package. This package contains the following main sub-packages
* devices - All the device drivers. Just look through some of the built-in drivers to get an idea for how they work. * devices - All the device drivers. Just look through some of the built-in drivers to get an idea for how they work.
* For details, see: ``devices.interface`` which defines the interface supported by device drivers and ``devices.usbms`` which * For details, see: ``devices.interface`` which defines the interface supported by device drivers and ``devices.usbms`` which
defines a generic driver that connects to a USBMS device. All USBMS based drivers in |app| inherit from it. defines a generic driver that connects to a USBMS device. All USBMS based drivers in calibre inherit from it.
* ebooks - All the ebook conversion/metadata code. A good starting point is ``calibre.ebooks.conversion.cli`` which is the * ebooks - All the ebook conversion/metadata code. A good starting point is ``calibre.ebooks.conversion.cli`` which is the
module powering the :command:`ebook-convert` command. The conversion process is controlled via ``conversion.plumber``. module powering the :command:`ebook-convert` command. The conversion process is controlled via ``conversion.plumber``.
@ -58,34 +58,34 @@ All the |app| python code is in the ``calibre`` package. This package contains t
* Ebook editing happens using a different container object. It is * Ebook editing happens using a different container object. It is
documented in :ref:`polish_api`. documented in :ref:`polish_api`.
* db - The database back-end. See :ref:`db_api` for the interface to the |app| library. * db - The database back-end. See :ref:`db_api` for the interface to the calibre library.
* content server: ``library.server`` is the |app| Content Server. * content server: ``library.server`` is the calibre Content Server.
* gui2 - The Graphical User Interface. GUI initialization happens in ``gui2.main`` and ``gui2.ui``. The ebook-viewer is in ``gui2.viewer``. The ebook editor is in ``gui2.tweak_book``. * gui2 - The Graphical User Interface. GUI initialization happens in ``gui2.main`` and ``gui2.ui``. The ebook-viewer is in ``gui2.viewer``. The ebook editor is in ``gui2.tweak_book``.
If you want to locate the entry points for all the various |app| executables, If you want to locate the entry points for all the various calibre executables,
look at the ``entry_points`` structure in `linux.py look at the ``entry_points`` structure in `linux.py
<https://github.com/kovidgoyal/calibre/blob/master/src/calibre/linux.py>`_. <https://github.com/kovidgoyal/calibre/blob/master/src/calibre/linux.py>`_.
If you need help understanding the code, post in the `development forum <http://www.mobileread.com/forums/forumdisplay.php?f=240>`_ If you need help understanding the code, post in the `development forum <http://www.mobileread.com/forums/forumdisplay.php?f=240>`_
and you will most likely get help from one of |app|'s many developers. and you will most likely get help from one of calibre's many developers.
Getting the code Getting the code
------------------ ------------------
You can get the |app| source code in two ways, using a version control system or You can get the calibre source code in two ways, using a version control system or
directly downloading a `tarball <http://status.calibre-ebook.com/dist/src>`_. directly downloading a `tarball <http://status.calibre-ebook.com/dist/src>`_.
|app| uses `Git <http://www.git-scm.com/>`_, a distributed version control calibre uses `Git <http://www.git-scm.com/>`_, a distributed version control
system. Git is available on all the platforms |app| supports. After system. Git is available on all the platforms calibre supports. After
installing Git, you can get the |app| source code with the command:: installing Git, you can get the calibre source code with the command::
git clone git://github.com/kovidgoyal/calibre.git git clone git://github.com/kovidgoyal/calibre.git
On Windows you will need the complete path name, that will be something like :file:`C:\\Program Files\\Git\\git.exe`. On Windows you will need the complete path name, that will be something like :file:`C:\\Program Files\\Git\\git.exe`.
|app| is a very large project with a very long source control history, so the calibre is a very large project with a very long source control history, so the
above can take a while (10mins to an hour depending on your internet speed). above can take a while (10mins to an hour depending on your internet speed).
If you want to get the code faster, the sourcecode for the latest release is If you want to get the code faster, the sourcecode for the latest release is
@ -99,7 +99,7 @@ Submitting your changes to be included
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you only plan to make a few small changes, you can make your changes and If you only plan to make a few small changes, you can make your changes and
create a "merge directive" which you can then attach to a ticket in the |app| create a "merge directive" which you can then attach to a ticket in the calibre
`bug tracker <https://bugs.launchpad.net/calibre>`_. To do this, make your `bug tracker <https://bugs.launchpad.net/calibre>`_. To do this, make your
changes, then run:: changes, then run::
@ -107,7 +107,7 @@ changes, then run::
git format-patch origin/master --stdout > my-changes git format-patch origin/master --stdout > my-changes
This will create a :file:`my-changes` file in the current directory, This will create a :file:`my-changes` file in the current directory,
simply attach that to a ticket on the |app| `bug tracker <https://bugs.launchpad.net/calibre>`_. simply attach that to a ticket on the calibre `bug tracker <https://bugs.launchpad.net/calibre>`_.
Note that this will include *all* the commits you have made. If you only want Note that this will include *all* the commits you have made. If you only want
to send some commits, you have to change ``origin/master`` above. To send only to send some commits, you have to change ``origin/master`` above. To send only
the last commit, use:: the last commit, use::
@ -121,10 +121,10 @@ commits::
Be careful to not include merges when using ``HEAD~n``. Be careful to not include merges when using ``HEAD~n``.
If you plan to do a lot of development on |app|, then the best method is to create a If you plan to do a lot of development on calibre, then the best method is to create a
`GitHub <http://github.com>`_ account. Below is a basic guide to setting up `GitHub <http://github.com>`_ account. Below is a basic guide to setting up
your own fork of calibre in a way that will allow you to submit pull requests your own fork of calibre in a way that will allow you to submit pull requests
for inclusion into the main |app| repository: for inclusion into the main calibre repository:
* Setup git on your machine as described in this article: `Setup Git <https://help.github.com/articles/set-up-git>`_ * Setup git on your machine as described in this article: `Setup Git <https://help.github.com/articles/set-up-git>`_
* Setup ssh keys for authentication to GitHub, as described here: `Generating SSH keys <https://help.github.com/articles/generating-ssh-keys>`_ * Setup ssh keys for authentication to GitHub, as described here: `Generating SSH keys <https://help.github.com/articles/generating-ssh-keys>`_
@ -145,7 +145,7 @@ for inclusion into the main |app| repository:
git pull upstream git pull upstream
You should also keep an eye on the |app| `development forum You should also keep an eye on the calibre `development forum
<http://www.mobileread.com/forums/forumdisplay.php?f=240>`_. Before making <http://www.mobileread.com/forums/forumdisplay.php?f=240>`_. Before making
major changes, you should discuss them in the forum or contact Kovid directly major changes, you should discuss them in the forum or contact Kovid directly
(his email address is all over the source code). (his email address is all over the source code).
@ -153,10 +153,10 @@ major changes, you should discuss them in the forum or contact Kovid directly
Windows development environment Windows development environment
--------------------------------- ---------------------------------
.. note:: You must also get the |app| source code separately as described above. .. note:: You must also get the calibre source code separately as described above.
Install |app| normally, using the Windows installer. Then open a Command Prompt and change to Install calibre normally, using the Windows installer. Then open a Command Prompt and change to
the previously checked out |app| code directory. For example:: the previously checked out calibre code directory. For example::
cd C:\Users\kovid\work\calibre cd C:\Users\kovid\work\calibre
@ -172,9 +172,9 @@ the command::
echo %CALIBRE_DEVELOP_FROM% echo %CALIBRE_DEVELOP_FROM%
Setting this environment variable means that |app| will now load all its Python code from the specified location. Setting this environment variable means that calibre will now load all its Python code from the specified location.
That's it! You are now ready to start hacking on the |app| code. For example, open the file :file:`src\\calibre\\__init__.py` That's it! You are now ready to start hacking on the calibre code. For example, open the file :file:`src\\calibre\\__init__.py`
in your favorite editor and add the line:: in your favorite editor and add the line::
print ("Hello, world!") print ("Hello, world!")
@ -184,14 +184,14 @@ near the top of the file. Now run the command :command:`calibredb`. The very fir
OS X development environment OS X development environment
------------------------------ ------------------------------
.. note:: You must also get the |app| source code separately as described above. .. note:: You must also get the calibre source code separately as described above.
Install |app| normally using the provided .dmg. Then open a Terminal and change to Install calibre normally using the provided .dmg. Then open a Terminal and change to
the previously checked out |app| code directory, for example:: the previously checked out calibre code directory, for example::
cd /Users/kovid/work/calibre cd /Users/kovid/work/calibre
calibre is the directory that contains the src and resources sub-directories. Ensure you have installed the |app| commandline tools via :guilabel:`Preferences->Advanced->Miscellaneous` in the |app| GUI. calibre is the directory that contains the src and resources sub-directories. Ensure you have installed the calibre commandline tools via :guilabel:`Preferences->Advanced->Miscellaneous` in the calibre GUI.
The next step is to create a bash script that will set the environment variable ``CALIBRE_DEVELOP_FROM`` to the absolute path of the src directory when running calibre in debug mode. The next step is to create a bash script that will set the environment variable ``CALIBRE_DEVELOP_FROM`` to the absolute path of the src directory when running calibre in debug mode.
@ -216,15 +216,15 @@ window, indicating that you are running from source.
Linux development environment Linux development environment
------------------------------ ------------------------------
.. note:: You must also get the |app| source code separately as described above. .. note:: You must also get the calibre source code separately as described above.
|app| is primarily developed on Linux. You have two choices in setting up the development environment. You can install the calibre is primarily developed on Linux. You have two choices in setting up the development environment. You can install the
|app| binary as normal and use that as a runtime environment to do your development. This approach is similar to that calibre binary as normal and use that as a runtime environment to do your development. This approach is similar to that
used in Windows and OS X. Alternatively, you can install |app| from source. Instructions for setting up a development used in Windows and OS X. Alternatively, you can install calibre from source. Instructions for setting up a development
environment from source are in the INSTALL file in the source tree. Here we will address using the binary at runtime, which is the environment from source are in the INSTALL file in the source tree. Here we will address using the binary at runtime, which is the
recommended method. recommended method.
Install |app| using the binary installer. Then open a terminal and change to the previously checked out |app| code directory, for example:: Install calibre using the binary installer. Then open a terminal and change to the previously checked out calibre code directory, for example::
cd /home/kovid/work/calibre cd /home/kovid/work/calibre
@ -239,24 +239,24 @@ the command::
echo $CALIBRE_DEVELOP_FROM echo $CALIBRE_DEVELOP_FROM
Setting this environment variable means that |app| will now load all its Python code from the specified location. Setting this environment variable means that calibre will now load all its Python code from the specified location.
That's it! You are now ready to start hacking on the |app| code. For example, open the file :file:`src/calibre/__init__.py` That's it! You are now ready to start hacking on the calibre code. For example, open the file :file:`src/calibre/__init__.py`
in your favorite editor and add the line:: in your favorite editor and add the line::
print ("Hello, world!") print ("Hello, world!")
near the top of the file. Now run the command :command:`calibredb`. The very first line of output should be ``Hello, world!``. near the top of the file. Now run the command :command:`calibredb`. The very first line of output should be ``Hello, world!``.
Having separate "normal" and "development" |app| installs on the same computer Having separate "normal" and "development" calibre installs on the same computer
----------------------------------------------------------------------------------------------------------------- -----------------------------------------------------------------------------------------------------------------
The |app| source tree is very stable and rarely breaks, but if you feel the need to run from source on a separate The calibre source tree is very stable and rarely breaks, but if you feel the need to run from source on a separate
test library and run the released |app| version with your everyday library, you can achieve this easily using test library and run the released calibre version with your everyday library, you can achieve this easily using
.bat files or shell scripts to launch |app|. The example below shows how to do this on Windows using .bat files (the .bat files or shell scripts to launch calibre. The example below shows how to do this on Windows using .bat files (the
instructions for other platforms are the same, just use a shell script instead of a .bat file) instructions for other platforms are the same, just use a shell script instead of a .bat file)
To launch the release version of |app| with your everyday library: To launch the release version of calibre with your everyday library:
calibre-normal.bat:: calibre-normal.bat::
@ -272,8 +272,8 @@ Debugging tips
---------------- ----------------
Python is a Python is a
dynamically typed language with excellent facilities for introspection. Kovid wrote the core |app| code without once dynamically typed language with excellent facilities for introspection. Kovid wrote the core calibre code without once
using a debugger. There are many strategies to debug |app| code: using a debugger. There are many strategies to debug calibre code:
Using print statements Using print statements
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
@ -340,21 +340,21 @@ Using the debugger in your favorite python IDE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is possible to use the builtin debugger in your favorite python IDE, if it It is possible to use the builtin debugger in your favorite python IDE, if it
supports remote debugging. The first step is to add the |app| src checkout to supports remote debugging. The first step is to add the calibre src checkout to
the ``PYTHONPATH`` in your IDE. In other words, the directory you set as the ``PYTHONPATH`` in your IDE. In other words, the directory you set as
``CALIBRE_DEVELOP_FROM`` above, must also be in the ``PYTHONPATH`` of your IDE. ``CALIBRE_DEVELOP_FROM`` above, must also be in the ``PYTHONPATH`` of your IDE.
Then place the IDE's remote debugger module into the :file:`src` subdirectory Then place the IDE's remote debugger module into the :file:`src` subdirectory
of the |app| source code checkout. Add whatever code is needed to launch the of the calibre source code checkout. Add whatever code is needed to launch the
remote debugger to |app| at the point of interest, for example in the main remote debugger to calibre at the point of interest, for example in the main
function. Then run |app| as normal. Your IDE should now be able to connect to function. Then run calibre as normal. Your IDE should now be able to connect to
the remote debugger running inside |app|. the remote debugger running inside calibre.
Executing arbitrary scripts in the |app| python environment Executing arbitrary scripts in the calibre python environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :command:`calibre-debug` command provides a couple of handy switches to execute your own The :command:`calibre-debug` command provides a couple of handy switches to execute your own
code, with access to the |app| modules:: code, with access to the calibre modules::
calibre-debug -c "some python code" calibre-debug -c "some python code"
@ -370,15 +370,15 @@ that the calibre environment is fully initialized, so you can use all the calibr
The ``--`` causes all subsequent arguments to be passed to your script. The ``--`` causes all subsequent arguments to be passed to your script.
Using |app| in your projects Using calibre in your projects
---------------------------------------- ----------------------------------------
It is possible to directly use |app| functions/code in your Python project. Two ways exist to do this: It is possible to directly use calibre functions/code in your Python project. Two ways exist to do this:
Binary install of |app| Binary install of calibre
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you have a binary install of |app|, you can use the Python interpreter bundled with |app|, like this:: If you have a binary install of calibre, you can use the Python interpreter bundled with calibre, like this::
calibre-debug /path/to/your/python/script.py -- arguments to your script calibre-debug /path/to/your/python/script.py -- arguments to your script
@ -386,17 +386,17 @@ Source install on Linux
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
In addition to using the above technique, if you do a source install on Linux, In addition to using the above technique, if you do a source install on Linux,
you can also directly import |app|, as follows:: you can also directly import calibre, as follows::
import init_calibre import init_calibre
import calibre import calibre
print calibre.__version__ print calibre.__version__
It is essential that you import the init_calibre module before any other |app| modules/packages as It is essential that you import the init_calibre module before any other calibre modules/packages as
it sets up the interpreter to run |app| code. it sets up the interpreter to run calibre code.
API documentation for various parts of |app| API documentation for various parts of calibre
------------------------------------------------ ------------------------------------------------
.. toctree:: .. toctree::

6
manual/diff.rst
View File

@ -3,7 +3,7 @@
Comparing E-books Comparing E-books
======================== ========================
|app| includes an integrated e-book comparison tool that can be used to see calibre includes an integrated e-book comparison tool that can be used to see
what has changed inside an ebook after editing or converting it. It can compare what has changed inside an ebook after editing or converting it. It can compare
books in the EPUB and AZW3 formats. books in the EPUB and AZW3 formats.
@ -68,10 +68,10 @@ right and the second file on the left.
Comparing the ORIGINAL_FMT to FMT Comparing the ORIGINAL_FMT to FMT
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When you do a conversion in |app| from a FMT to itself, the original file is When you do a conversion in calibre from a FMT to itself, the original file is
saved as ORIGINAL_FMT. You can see what was changed by the conversion, by right saved as ORIGINAL_FMT. You can see what was changed by the conversion, by right
clicking on the ORIGINAL_FMT entry in the :ref:`book_details` panel in the main clicking on the ORIGINAL_FMT entry in the :ref:`book_details` panel in the main
|app| window and selecting :guilabel:`Compare to FMT`. The comparison view will calibre window and selecting :guilabel:`Compare to FMT`. The comparison view will
open with ORIGINAL_FMT on the left and FMT on the right. open with ORIGINAL_FMT on the left and FMT on the right.
Comparing a checkpoint to the current state of the book while editing Comparing a checkpoint to the current state of the book while editing

20
manual/edit.rst
View File

@ -3,13 +3,13 @@
Editing E-books Editing E-books
======================== ========================
|app| has an integrated e-book editor that can be used to edit books in the calibre has an integrated e-book editor that can be used to edit books in the
EPUB and AZW3 (Kindle) formats. The editor shows you the HTML and CSS that is EPUB and AZW3 (Kindle) formats. The editor shows you the HTML and CSS that is
used internally inside the book files, with a live preview that updates as you used internally inside the book files, with a live preview that updates as you
make changes. It also contains various automated tools to perform common make changes. It also contains various automated tools to perform common
cleanup and fixing tasks. cleanup and fixing tasks.
You can use this editor by right clicking on any book in |app| and selecting You can use this editor by right clicking on any book in calibre and selecting
:guilabel:`Edit book`. :guilabel:`Edit book`.
.. image:: images/edit-book.png .. image:: images/edit-book.png
@ -26,7 +26,7 @@ Basic workflow
--------------- ---------------
.. note:: .. note::
A video tour of the |app| editor is available `here A video tour of the calibre editor is available `here
<http://calibre-ebook.com/demo#tutorials>`_. <http://calibre-ebook.com/demo#tutorials>`_.
When you first open a book with the Edit book tool, you will be presented with When you first open a book with the Edit book tool, you will be presented with
@ -94,7 +94,7 @@ Renaming files
You can rename an individual file by right clicking it and selecting You can rename an individual file by right clicking it and selecting
:guilabel:`Rename`. Renaming a file automatically updates all links and :guilabel:`Rename`. Renaming a file automatically updates all links and
references to it throughout the book. So all you have to do is provide the new references to it throughout the book. So all you have to do is provide the new
name, |app| will take care of the rest. name, calibre will take care of the rest.
You can also bulk rename many files at once. This is useful You can also bulk rename many files at once. This is useful
if you want the files to have some simple name pattern. For example you might if you want the files to have some simple name pattern. For example you might
@ -115,7 +115,7 @@ when viewing the book in a typical ebook reader.
To merge multiple files together, select them by holding the Ctrl key and To merge multiple files together, select them by holding the Ctrl key and
clicking on them (make sure you only select files of one type, either all HTML clicking on them (make sure you only select files of one type, either all HTML
files or all CSS files and so on). Then right click and select merge. That's files or all CSS files and so on). Then right click and select merge. That's
all, |app| will merge the files, automatically taking care of migrating all all, calibre will merge the files, automatically taking care of migrating all
links and references to the merged files. Note that merging files can sometimes links and references to the merged files. Note that merging files can sometimes
cause text styling to change, since the individual files could have used cause text styling to change, since the individual files could have used
different stylesheets. different stylesheets.
@ -142,8 +142,8 @@ HTML file that acts as the title page/cover for the book. You can mark an HTML
file as the titlepage when editing EPUBs by right-clicking. Be careful that the file as the titlepage when editing EPUBs by right-clicking. Be careful that the
file you mark contains only the cover information. If it contains other file you mark contains only the cover information. If it contains other
content, such as the first chapter, then that content will be lost if the user content, such as the first chapter, then that content will be lost if the user
ever converts the EPUB file in |app| to another format. This is because when ever converts the EPUB file in calibre to another format. This is because when
converting, |app| assumes that the marked title page contains only the cover converting, calibre assumes that the marked title page contains only the cover
and no other content. and no other content.
Deleting files Deleting files
@ -191,7 +191,7 @@ Linking stylesheets to HTML files efficiently
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As a convenience, you can select multiple HTML files in the Files Browser, As a convenience, you can select multiple HTML files in the Files Browser,
right click and choose Link stylesheets to have |app| automatically insert the right click and choose Link stylesheets to have calibre automatically insert the
<link> tags for those stylesheets into all the selected HTML files. <link> tags for those stylesheets into all the selected HTML files.
.. raw:: html epub .. raw:: html epub
@ -304,7 +304,7 @@ Some of the checks performed are:
* Malformed HTML markup. Any HTML markup that does not parse as well-formed * Malformed HTML markup. Any HTML markup that does not parse as well-formed
XML is reported. Correcting it will ensure that your markup works as XML is reported. Correcting it will ensure that your markup works as
intended in all contexts. |app| can also auto-fix these errors, but intended in all contexts. calibre can also auto-fix these errors, but
auto-fixing can sometimes have unexpected effects, so use with care. As auto-fixing can sometimes have unexpected effects, so use with care. As
always, a checkpoint is created before auto-fixing so you can easily always, a checkpoint is created before auto-fixing so you can easily
revert all changes. Auto-fixing works by parsing the markup using the revert all changes. Auto-fixing works by parsing the markup using the
@ -417,7 +417,7 @@ Insert inline Table of Contents
Normally in ebooks, the Table of Contents is separate from the main text and is Normally in ebooks, the Table of Contents is separate from the main text and is
typically accessed via a special Table of Contents button/menu in the ebook typically accessed via a special Table of Contents button/menu in the ebook
reading device. You can also have |app| automatically generate an *inline* reading device. You can also have calibre automatically generate an *inline*
Table of Contents that becomes part of the text of the book. It is Table of Contents that becomes part of the text of the book. It is
generated based on the currently defined Table of Contents. generated based on the currently defined Table of Contents.

408
manual/faq.rst
View File

@ -13,9 +13,9 @@ Ebook Format Conversion
:depth: 1 :depth: 1
:local: :local:
What formats does |app| support conversion to/from? What formats does calibre support conversion to/from?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| supports the conversion of many input formats to many output formats. calibre supports the conversion of many input formats to many output formats.
It can convert every input format in the following list, to every output format. It can convert every input format in the following list, to every output format.
*Input Formats:* CBZ, CBR, CBC, CHM, DJVU, DOCX, EPUB, FB2, HTML, HTMLZ, LIT, LRF, MOBI, ODT, PDF, PRC, PDB, PML, RB, RTF, SNB, TCR, TXT, TXTZ *Input Formats:* CBZ, CBR, CBC, CHM, DJVU, DOCX, EPUB, FB2, HTML, HTMLZ, LIT, LRF, MOBI, ODT, PDF, PRC, PDB, PML, RB, RTF, SNB, TCR, TXT, TXTZ
@ -24,10 +24,10 @@ It can convert every input format in the following list, to every output format.
.. note :: .. note ::
PRC is a generic format, |app| supports PRC files with TextRead and MOBIBook headers. PRC is a generic format, calibre supports PRC files with TextRead and MOBIBook headers.
PDB is also a generic format. |app| supports eReader, Plucker, PML and zTxt PDB files. PDB is also a generic format. calibre supports eReader, Plucker, PML and zTxt PDB files.
DJVU support is only for converting DJVU files that contain embedded text. These are typically generated by OCR software. DJVU support is only for converting DJVU files that contain embedded text. These are typically generated by OCR software.
MOBI books can be of two types Mobi6 and KF8. |app| fully supports both. MOBI files often have .azw or .azw3 file extensions. MOBI books can be of two types Mobi6 and KF8. calibre fully supports both. MOBI files often have .azw or .azw3 file extensions.
DOCX files from Microsoft Word 2007 and newer are supported. DOCX files from Microsoft Word 2007 and newer are supported.
.. _best-source-formats: .. _best-source-formats:
@ -47,8 +47,8 @@ PDF is a terrible format to convert from. For a list of the various issues you w
How do I convert my file containing non-English characters, or smart quotes? How do I convert my file containing non-English characters, or smart quotes?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are two aspects to this problem: There are two aspects to this problem:
1. Knowing the encoding of the source file: |app| tries to guess what character encoding your source files use, but often, this is impossible, so you need to tell it what encoding to use. This can be done in the GUI via the :guilabel:`Input character encoding` field in the :guilabel:`Look & Feel` section. The command-line tools all have an :option:`--input-encoding` option. 1. Knowing the encoding of the source file: calibre tries to guess what character encoding your source files use, but often, this is impossible, so you need to tell it what encoding to use. This can be done in the GUI via the :guilabel:`Input character encoding` field in the :guilabel:`Look & Feel` section. The command-line tools all have an :option:`--input-encoding` option.
2. When adding HTML files to |app|, you may need to tell |app| what encoding the files are in. To do this go to :guilabel:`Preferences->Advanced->Plugins->File Type plugins` and customize the HTML2Zip plugin, telling it what encoding your HTML files are in. Now when you add HTML files to |app| they will be correctly processed. HTML files from different sources often have different encodings, so you may have to change this setting repeatedly. A common encoding for many files from the web is ``cp1252`` and I would suggest you try that first. Note that when converting HTML files, leave the input encoding setting mentioned above blank. This is because the HTML2ZIP plugin automatically converts the HTML files to a standard encoding (utf-8). 2. When adding HTML files to calibre, you may need to tell calibre what encoding the files are in. To do this go to :guilabel:`Preferences->Advanced->Plugins->File Type plugins` and customize the HTML2Zip plugin, telling it what encoding your HTML files are in. Now when you add HTML files to calibre they will be correctly processed. HTML files from different sources often have different encodings, so you may have to change this setting repeatedly. A common encoding for many files from the web is ``cp1252`` and I would suggest you try that first. Note that when converting HTML files, leave the input encoding setting mentioned above blank. This is because the HTML2ZIP plugin automatically converts the HTML files to a standard encoding (utf-8).
What's the deal with Table of Contents in MOBI files? What's the deal with Table of Contents in MOBI files?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -114,23 +114,23 @@ Then, just add this HTML file to the GUI and use the convert button to create
your ebook. You can use the option in the Table of Contents section in the your ebook. You can use the option in the Table of Contents section in the
conversion dialog to control how the Table of Contents is generated. conversion dialog to control how the Table of Contents is generated.
.. note:: By default, when adding HTML files, |app| follows links in the files .. note:: By default, when adding HTML files, calibre follows links in the files
in *depth first* order. This means that if file A.html links to B.html and in *depth first* order. This means that if file A.html links to B.html and
C.html and D.html, but B.html also links to D.html, then the files will be C.html and D.html, but B.html also links to D.html, then the files will be
in the order A.html, B.html, D.html, C.html. If instead you want the order in the order A.html, B.html, D.html, C.html. If instead you want the order
to be A.html, B.html, C.html, D.html then you must tell |app| to add your to be A.html, B.html, C.html, D.html then you must tell calibre to add your
files in *breadth first* order. Do this by going to Preferences->Plugins files in *breadth first* order. Do this by going to Preferences->Plugins
and customizing the HTML to ZIP plugin. and customizing the HTML to ZIP plugin.
The EPUB I produced with |app| is not valid? The EPUB I produced with calibre is not valid?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| does not guarantee that an EPUB produced by it is valid. The only calibre does not guarantee that an EPUB produced by it is valid. The only
guarantee it makes is that if you feed it valid XHTML 1.1 + CSS 2.1 it will guarantee it makes is that if you feed it valid XHTML 1.1 + CSS 2.1 it will
output a valid EPUB. |app| tries hard to ensure that EPUBs it produces actually output a valid EPUB. calibre tries hard to ensure that EPUBs it produces actually
work as intended on a wide variety of devices, a goal that is incompatible with work as intended on a wide variety of devices, a goal that is incompatible with
producing valid EPUBs, and one that is far more important to the vast majority producing valid EPUBs, and one that is far more important to the vast majority
of its users. If you need a tool that always produces valid EPUBs, |app| is not of its users. If you need a tool that always produces valid EPUBs, calibre is not
for you. for you.
How do I use some of the advanced features of the conversion tools? How do I use some of the advanced features of the conversion tools?
@ -149,9 +149,9 @@ Device Integration
:depth: 1 :depth: 1
:local: :local:
What devices does |app| support? What devices does calibre support?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| can directly connect to all the major (and most of the minor) ebook calibre can directly connect to all the major (and most of the minor) ebook
reading devices, smarthphones, tablets, etc. In addition, using the reading devices, smarthphones, tablets, etc. In addition, using the
:guilabel:`Connect to folder` function you can use it with any ebook reader :guilabel:`Connect to folder` function you can use it with any ebook reader
that exports itself as a USB disk. You can even connect to Apple devices (via that exports itself as a USB disk. You can even connect to Apple devices (via
@ -159,15 +159,15 @@ iTunes), using the :guilabel:`Connect to iTunes` function.
.. _devsupport: .. _devsupport:
How can I help get my device supported in |app|? How can I help get my device supported in calibre?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If your device appears as a USB disk to the operating system, adding support for it to |app| is very easy. If your device appears as a USB disk to the operating system, adding support for it to calibre is very easy.
We just need some information from you: We just need some information from you:
* Complete list of ebook formats that your device supports. * Complete list of ebook formats that your device supports.
* Is there a special directory on the device in which all ebook files should be placed? Also does the device detect files placed in sub directories? * Is there a special directory on the device in which all ebook files should be placed? Also does the device detect files placed in sub directories?
* We also need information about your device that |app| will collect automatically. First, if your * We also need information about your device that calibre will collect automatically. First, if your
device supports SD cards, insert them. Then connect your device to the computer. In calibre go to :guilabel:`Preferences->Advanced->Miscellaneous` device supports SD cards, insert them. Then connect your device to the computer. In calibre go to :guilabel:`Preferences->Advanced->Miscellaneous`
and click the "Debug device detection" button. This will create some debug output. Copy it to a file and click the "Debug device detection" button. This will create some debug output. Copy it to a file
and repeat the process, this time with your device disconnected from your computer. and repeat the process, this time with your device disconnected from your computer.
@ -175,27 +175,27 @@ We just need some information from you:
device. device.
Once you send us the output for a particular operating system, support for the device in that operating system Once you send us the output for a particular operating system, support for the device in that operating system
will appear in the next release of |app|. To send us the output, open a bug report and attach the output to it. will appear in the next release of calibre. To send us the output, open a bug report and attach the output to it.
See `calibre bugs <http://calibre-ebook.com/bugs>`_. See `calibre bugs <http://calibre-ebook.com/bugs>`_.
My device is not being detected by |app|? My device is not being detected by calibre?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Follow these steps to find the problem: Follow these steps to find the problem:
* Make sure that you are connecting only a single device to your computer * Make sure that you are connecting only a single device to your computer
at a time. Do not have another |app| supported device like an iPhone/iPad at a time. Do not have another calibre supported device like an iPhone/iPad
etc. at the same time. etc. at the same time.
* If you are connecting an Apple iDevice (iPad, iPod Touch, iPhone), use * If you are connecting an Apple iDevice (iPad, iPod Touch, iPhone), use
the 'Connect to iTunes' method in the 'Getting started' instructions in the 'Connect to iTunes' method in the 'Getting started' instructions in
`Calibre + Apple iDevices: Start here <http://www.mobileread.com/forums/showthread.php?t=118559>`_. `Calibre + Apple iDevices: Start here <http://www.mobileread.com/forums/showthread.php?t=118559>`_.
* Make sure you are running the latest version of |app|. The latest version * Make sure you are running the latest version of calibre. The latest version
can always be downloaded from `the calibre website <http://calibre-ebook.com/download>`_. can always be downloaded from `the calibre website <http://calibre-ebook.com/download>`_.
You can tell what version of |app| you are currently running by looking You can tell what version of calibre you are currently running by looking
at the bottom line of the main |app| window. at the bottom line of the main calibre window.
* Ensure your operating system is seeing the device. That is, the device * Ensure your operating system is seeing the device. That is, the device
should show up in Windows Explorer (in Windows) or Finder (in OS X). should show up in Windows Explorer (in Windows) or Finder (in OS X).
* In |app|, go to Preferences->Ignored Devices and check that your device * In calibre, go to Preferences->Ignored Devices and check that your device
is not being ignored is not being ignored
* If all the above steps fail, go to :guilabel:`Preferences->Miscellaneous` and click * If all the above steps fail, go to :guilabel:`Preferences->Miscellaneous` and click
:guilabel:`Debug device detection` with your device attached and post the output as a :guilabel:`Debug device detection` with your device attached and post the output as a
@ -204,45 +204,45 @@ Follow these steps to find the problem:
My device is non-standard or unusual. What can I do to connect to it? My device is non-standard or unusual. What can I do to connect to it?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In addition to the :guilabel:`Connect to Folder` function found under the Connect/Share button, |app| provides a ``User Defined`` device plugin that can be used to connect to any USB device that shows up as a disk drive in your operating system. Note: on windows, the device must have a drive letter for calibre to use it. See the device plugin ``Preferences -> Plugins -> Device Plugins -> User Defined`` and ``Preferences -> Miscellaneous -> Get information to setup the user defined device`` for more information. Note that if you are using the user defined plugin for a device normally detected by a builtin |app| plugin, you must disable the builtin plugin first, so that your user defined plugin is used instead. In addition to the :guilabel:`Connect to Folder` function found under the Connect/Share button, calibre provides a ``User Defined`` device plugin that can be used to connect to any USB device that shows up as a disk drive in your operating system. Note: on windows, the device must have a drive letter for calibre to use it. See the device plugin ``Preferences -> Plugins -> Device Plugins -> User Defined`` and ``Preferences -> Miscellaneous -> Get information to setup the user defined device`` for more information. Note that if you are using the user defined plugin for a device normally detected by a builtin calibre plugin, you must disable the builtin plugin first, so that your user defined plugin is used instead.
How does |app| manage collections on my SONY reader? How does calibre manage collections on my SONY reader?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When |app| connects with the reader, it retrieves all collections for the books on the reader. The collections When calibre connects with the reader, it retrieves all collections for the books on the reader. The collections
of which books are members are shown on the device view. of which books are members are shown on the device view.
When you send a book to the reader, |app| will add the book to collections based on the metadata for that book. By When you send a book to the reader, calibre will add the book to collections based on the metadata for that book. By
default, collections are created from tags and series. You can control what metadata is used by going to default, collections are created from tags and series. You can control what metadata is used by going to
:guilabel:`Preferences->Advanced->Plugins->Device Interface plugins` and customizing the SONY device interface plugin. If you remove all :guilabel:`Preferences->Advanced->Plugins->Device Interface plugins` and customizing the SONY device interface plugin. If you remove all
values, |app| will not add the book to any collection. values, calibre will not add the book to any collection.
Collection management is largely controlled by the 'Metadata management' option found at Collection management is largely controlled by the 'Metadata management' option found at
:guilabel:`Preferences->Import/Export->Sending books to devices`. If set to 'Manual' (the default), managing collections is left to :guilabel:`Preferences->Import/Export->Sending books to devices`. If set to 'Manual' (the default), managing collections is left to
the user; |app| will not delete already existing collections for a book on your reader when you resend the the user; calibre will not delete already existing collections for a book on your reader when you resend the
book to the reader, but |app| will add the book to collections if necessary. To ensure that the collections book to the reader, but calibre will add the book to collections if necessary. To ensure that the collections
for a book are based only on current |app| metadata, first delete the books from the reader, then resend the for a book are based only on current calibre metadata, first delete the books from the reader, then resend the
books. You can edit collections directly on the device view by double-clicking or right-clicking in the books. You can edit collections directly on the device view by double-clicking or right-clicking in the
collections column. collections column.
If 'Metadata management' is set to 'Only on send', then |app| will manage collections more aggressively. If 'Metadata management' is set to 'Only on send', then calibre will manage collections more aggressively.
Collections will be built using |app| metadata exclusively. Sending a book to the reader will correct the Collections will be built using calibre metadata exclusively. Sending a book to the reader will correct the
collections for that book so its collections exactly match the book's metadata, adding and deleting collections for that book so its collections exactly match the book's metadata, adding and deleting
collections as necessary. Editing collections on the device view is not permitted, because collections not in collections as necessary. Editing collections on the device view is not permitted, because collections not in
the metadata will be removed automatically. the metadata will be removed automatically.
If 'Metadata management' is set to 'Automatic management', then |app| will update metadata and collections If 'Metadata management' is set to 'Automatic management', then calibre will update metadata and collections
both when the reader is connected and when books are sent. When calibre detects the reader and generates the both when the reader is connected and when books are sent. When calibre detects the reader and generates the
list of books on the reader, it will send metadata from the library to the reader for all books on the reader list of books on the reader, it will send metadata from the library to the reader for all books on the reader
that are in the library (On device is True), adding and removing books from collections as indicated by the that are in the library (On device is True), adding and removing books from collections as indicated by the
metadata and device customization. When a book is sent, |app| corrects the metadata for that book, adding and metadata and device customization. When a book is sent, calibre corrects the metadata for that book, adding and
deleting collections. Manual editing of metadata on the device view is not allowed. Note that this option deleting collections. Manual editing of metadata on the device view is not allowed. Note that this option
specifies sending metadata, not books. The book files on the reader are not changed. specifies sending metadata, not books. The book files on the reader are not changed.
In summary, choose 'manual management' if you want to manage collections yourself. Collections for a book In summary, choose 'manual management' if you want to manage collections yourself. Collections for a book
will never be removed by |app|, but can be removed by you by editing on the device view. Choose 'Only on will never be removed by calibre, but can be removed by you by editing on the device view. Choose 'Only on
send' if you want |app| to manage collections when you send a book, adding books to and removing books from send' if you want calibre to manage collections when you send a book, adding books to and removing books from
collections as needed. Choose 'Automatic management' if you want |app| to keep collections up to date collections as needed. Choose 'Automatic management' if you want calibre to keep collections up to date
whenever the reader is connected. whenever the reader is connected.
If you use multiple installations of calibre to manage your reader, then option 'Automatic management' may not If you use multiple installations of calibre to manage your reader, then option 'Automatic management' may not
@ -250,7 +250,7 @@ be what you want. Connecting the reader to one library will reset the metadata
Connecting to the other library will reset the metadata to what is in that other library. Metadata in books Connecting to the other library will reset the metadata to what is in that other library. Metadata in books
found in both libraries will be flopped back and forth. found in both libraries will be flopped back and forth.
Can I use both |app| and the SONY software to manage my reader? Can I use both calibre and the SONY software to manage my reader?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Yes, you can use both, provided you do not run them at the same time. That is, you should use the following sequence: Yes, you can use both, provided you do not run them at the same time. That is, you should use the following sequence:
@ -258,7 +258,7 @@ Connect reader->Use one of the programs->Disconnect reader. Reconnect reader->Us
The underlying reason is that the Reader uses a single file to keep track The underlying reason is that the Reader uses a single file to keep track
of 'meta' information, such as collections, and this is written to by both of 'meta' information, such as collections, and this is written to by both
|app| and the Sony software when either updates something on the Reader. calibre and the Sony software when either updates something on the Reader.
The file will be saved when the Reader is (safely) disconnected, so using one The file will be saved when the Reader is (safely) disconnected, so using one
or the other is safe if there's a disconnection between them, but if or the other is safe if there's a disconnection between them, but if
you're not the type to remember this, then the simple answer is to stick you're not the type to remember this, then the simple answer is to stick
@ -275,27 +275,27 @@ If you don't want to uninstall it altogether, there are a couple of tricks you c
simplest is to simply re-name the executable file that launches the library program. More detail simplest is to simply re-name the executable file that launches the library program. More detail
`in the forums <http://www.mobileread.com/forums/showthread.php?t=65809>`_. `in the forums <http://www.mobileread.com/forums/showthread.php?t=65809>`_.
How do I use |app| with my iPad/iPhone/iPod touch? How do I use calibre with my iPad/iPhone/iPod touch?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Over the air Over the air
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
The easiest way to browse your |app| collection on your Apple device The easiest way to browse your calibre collection on your Apple device
(iPad/iPhone/iPod) is by using the |app| content server, which makes your (iPad/iPhone/iPod) is by using the calibre content server, which makes your
collection available over the net. First perform the following steps in |app| collection available over the net. First perform the following steps in calibre
* Set the Preferred Output Format in |app| to EPUB (The output format can be * Set the Preferred Output Format in calibre to EPUB (The output format can be
set under :guilabel:`Preferences->Interface->Behavior`) set under :guilabel:`Preferences->Interface->Behavior`)
* Set the output profile to iPad (this will work for iPhone/iPods as well), * Set the output profile to iPad (this will work for iPhone/iPods as well),
under :guilabel:`Preferences->Conversion->Common Options->Page Setup` under :guilabel:`Preferences->Conversion->Common Options->Page Setup`
* Convert the books you want to read on your iDevice to EPUB format by * Convert the books you want to read on your iDevice to EPUB format by
selecting them and clicking the Convert button. selecting them and clicking the Convert button.
* Turn on the Content Server by clicking the :guilabel:`Connect/Share` button * Turn on the Content Server by clicking the :guilabel:`Connect/Share` button
and leave |app| running. You can also tell |app| to automatically start the and leave calibre running. You can also tell calibre to automatically start the
content server via :guilabel:`Preferences->Sharing over the net`. content server via :guilabel:`Preferences->Sharing over the net`.
There are many apps for your iDevice that can connect to |app|. Here we There are many apps for your iDevice that can connect to calibre. Here we
describe using two of them, iBooks and Stanza. describe using two of them, iBooks and Stanza.
Using Stanza Using Stanza
@ -304,7 +304,7 @@ Using Stanza
You should be able to access your books on your iPhone by opening Stanza. Go to You should be able to access your books on your iPhone by opening Stanza. Go to
"Get Books" and then click the "Shared" tab. Under Shared you will see an entry "Get Books" and then click the "Shared" tab. Under Shared you will see an entry
"Books in calibre". If you don't, make sure your iPad/iPhone is connected using "Books in calibre". If you don't, make sure your iPad/iPhone is connected using
the WiFi network in your house, not 3G. If the |app| catalog is still not the WiFi network in your house, not 3G. If the calibre catalog is still not
detected in Stanza, you can add it manually in Stanza. To do this, click the detected in Stanza, you can add it manually in Stanza. To do this, click the
"Shared" tab, then click the "Edit" button and then click "Add book source" to "Shared" tab, then click the "Edit" button and then click "Add book source" to
add a new book source. In the Add Book Source screen enter whatever name you add a new book source. In the Add Book Source screen enter whatever name you
@ -313,7 +313,7 @@ like and in the URL field, enter the following::
http://192.168.1.2:8080/ http://192.168.1.2:8080/
Replace ``192.168.1.2`` with the local IP address of the computer running Replace ``192.168.1.2`` with the local IP address of the computer running
|app|. If you have changed the port the |app| content server is running on, you calibre. If you have changed the port the calibre content server is running on, you
will have to change ``8080`` as well to the new port. The local IP address is will have to change ``8080`` as well to the new port. The local IP address is
the IP address you computer is assigned on your home network. A quick Google the IP address you computer is assigned on your home network. A quick Google
search will tell you how to find out your local IP address. Now click "Save" search will tell you how to find out your local IP address. Now click "Save"
@ -332,7 +332,7 @@ running the calibre server, like this::
http://192.168.1.2:8080/ http://192.168.1.2:8080/
Replace ``192.168.1.2`` with the local IP address of the computer running Replace ``192.168.1.2`` with the local IP address of the computer running
|app|. If you have changed the port the |app| content server is running on, you calibre. If you have changed the port the calibre content server is running on, you
will have to change ``8080`` as well to the new port. The local IP address is will have to change ``8080`` as well to the new port. The local IP address is
the IP address you computer is assigned on your home network. A quick Google the IP address you computer is assigned on your home network. A quick Google
search will tell you how to find out your local IP address. search will tell you how to find out your local IP address.
@ -352,7 +352,7 @@ higher. Linux is not supported (iTunes is not available in linux) and OS X
newer than 10.8 is not supported, as Apple removed the facility to use iTunes newer than 10.8 is not supported, as Apple removed the facility to use iTunes
to manage books, replacing it with iBooks. to manage books, replacing it with iBooks.
How do I use |app| with my Android phone/tablet or Kindle Fire HD? How do I use calibre with my Android phone/tablet or Kindle Fire HD?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are two ways that you can connect your Android device to calibre. Using a USB cable -- or wirelessly, over the air. There are two ways that you can connect your Android device to calibre. Using a USB cable -- or wirelessly, over the air.
@ -368,12 +368,12 @@ Android: Some examples (in no particular order):
Using a USB cable Using a USB cable
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
Simply plug your device into the computer with a USB cable. |app| should Simply plug your device into the computer with a USB cable. calibre should
automatically detect the device and then you can transfer books to it by automatically detect the device and then you can transfer books to it by
clicking the Send to Device button. |app| does not have support for every clicking the Send to Device button. calibre does not have support for every
single android device out there, so if your device is not automatically single android device out there, so if your device is not automatically
detected, follow the instructions at :ref:`devsupport` to get your device detected, follow the instructions at :ref:`devsupport` to get your device
supported in |app|. supported in calibre.
.. note:: With newer Android devices, the USB connection is not supported on .. note:: With newer Android devices, the USB connection is not supported on
Windows XP. If you are on Windows XP, you should use one of the Windows XP. If you are on Windows XP, you should use one of the
@ -385,33 +385,33 @@ Over the air
The easiest way to transfer books wirelessly to your Android device is to use The easiest way to transfer books wirelessly to your Android device is to use
the `Calibre Companion <http://www.multipie.co.uk/calibre-companion/>`_ the `Calibre Companion <http://www.multipie.co.uk/calibre-companion/>`_
Android app. This app is maintained by a core calibre developer and allows Android app. This app is maintained by a core calibre developer and allows
|app| to connect to your Android device wirelessly, just as though you calibre to connect to your Android device wirelessly, just as though you
plugged in the device with a USB cable. You can browse files on the device plugged in the device with a USB cable. You can browse files on the device
in |app| and use the :guilabel:`Send to device` button to transfer files to in calibre and use the :guilabel:`Send to device` button to transfer files to
your device wirelessly. your device wirelessly.
|app| also has a builtin web server, the :guilabel:`Content Server`. calibre also has a builtin web server, the :guilabel:`Content Server`.
You can browse your |app| collection on your Android device is by using the You can browse your calibre collection on your Android device is by using the
calibre content server, which makes your collection available over the net. calibre content server, which makes your collection available over the net.
First perform the following steps in |app| First perform the following steps in calibre
* Set the :guilabel:`Preferred Output Format` in |app| to EPUB for normal Android devices or MOBI for Kindles (The output format can be set under :guilabel:`Preferences->Interface->Behavior`) * Set the :guilabel:`Preferred Output Format` in calibre to EPUB for normal Android devices or MOBI for Kindles (The output format can be set under :guilabel:`Preferences->Interface->Behavior`)
* Convert the books you want to read on your device to EPUB/MOBI format by selecting them and clicking the Convert button. * Convert the books you want to read on your device to EPUB/MOBI format by selecting them and clicking the Convert button.
* Turn on the Content Server in |app|'s preferences and leave |app| running. * Turn on the Content Server in calibre's preferences and leave calibre running.
Now on your Android device, open the browser and browse to Now on your Android device, open the browser and browse to
http://192.168.1.2:8080/ http://192.168.1.2:8080/
Replace ``192.168.1.2`` with the local IP address of the computer running Replace ``192.168.1.2`` with the local IP address of the computer running
|app|. If your local network supports the use of computer names, you can calibre. If your local network supports the use of computer names, you can
replace the IP address with the network name of the computer. If you have replace the IP address with the network name of the computer. If you have
changed the port the |app| content server is running on, you will have to changed the port the calibre content server is running on, you will have to
change ``8080`` as well to the new port. change ``8080`` as well to the new port.
The local IP address is the IP address you computer is assigned on your home The local IP address is the IP address you computer is assigned on your home
network. A quick Google search will tell you how to find out your local IP network. A quick Google search will tell you how to find out your local IP
address. You can now browse your book collection and download books from |app| address. You can now browse your book collection and download books from calibre
to your device to open with whatever ebook reading software you have on your to your device to open with whatever ebook reading software you have on your
android device. android device.
@ -420,10 +420,10 @@ example, in Aldiko, click My Catalogs, then + to add a catalog, then give the
catalog a title such as "Calibre" and provide the URL listed above. You can now catalog a title such as "Calibre" and provide the URL listed above. You can now
browse the Calibre library and download directly into the reading software. browse the Calibre library and download directly into the reading software.
Can I access my |app| books using the web browser in my Kindle or other reading device? Can I access my calibre books using the web browser in my Kindle or other reading device?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| has a *Content Server* that exports the books in |app| as a web page. You can turn it on under calibre has a *Content Server* that exports the books in calibre as a web page. You can turn it on under
:guilabel:`Preferences->Network->Sharing over the net`. Then just point the web browser on your device to the computer running :guilabel:`Preferences->Network->Sharing over the net`. Then just point the web browser on your device to the computer running
the Content Server and you will be able to browse your book collection. For example, if the computer running the Content Server and you will be able to browse your book collection. For example, if the computer running
the server has IP address 63.45.128.5, in the browser, you would type:: the server has IP address 63.45.128.5, in the browser, you would type::
@ -431,7 +431,7 @@ the server has IP address 63.45.128.5, in the browser, you would type::
http://63.45.128.5:8080 http://63.45.128.5:8080
Some devices, like the Kindle (1/2/DX), do not allow you to access port 8080 (the default port on which the content Some devices, like the Kindle (1/2/DX), do not allow you to access port 8080 (the default port on which the content
server runs. In that case, change the port in the |app| Preferences to 80. (On some operating systems, server runs. In that case, change the port in the calibre Preferences to 80. (On some operating systems,
you may not be able to run the server on a port number less than 1024 because of security settings. In you may not be able to run the server on a port number less than 1024 because of security settings. In
this case the simplest solution is to adjust your router to forward requests on port 80 to port 8080). this case the simplest solution is to adjust your router to forward requests on port 80 to port 8080).
@ -440,31 +440,31 @@ I get the error message "Failed to start content server: Port 8080 not free on '
The most likely cause of this is your antivirus program. Try temporarily disabling it and see if it does the trick. The most likely cause of this is your antivirus program. Try temporarily disabling it and see if it does the trick.
I cannot send emails using |app|? I cannot send emails using calibre?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Because of the large amount of spam in email, sending email can be tricky, as different mail servers use different strategies to block email. Because of the large amount of spam in email, sending email can be tricky, as different mail servers use different strategies to block email.
The most common problem is if you are sending email directly (without a mail relay) in |app|. Many servers (for example, Amazon) block email The most common problem is if you are sending email directly (without a mail relay) in calibre. Many servers (for example, Amazon) block email
that does not come from a well known relay. The most robust way to setup email sending in |app| is to do the following: that does not come from a well known relay. The most robust way to setup email sending in calibre is to do the following:
* Create a free GMX account at `GMX <http://www.gmx.com>`_. * Create a free GMX account at `GMX <http://www.gmx.com>`_.
* Goto Preferences->Email in |app| and click the "Use GMX" button and fill in the information asked for. * Goto Preferences->Email in calibre and click the "Use GMX" button and fill in the information asked for.
* |app| will then use GMX to send the mail. * calibre will then use GMX to send the mail.
* If you are sending to your Kindle, remember to update the email preferences * If you are sending to your Kindle, remember to update the email preferences
on your Amazon Kindle page to allow email sent from your GMX email on your Amazon Kindle page to allow email sent from your GMX email
address. Also note that Amazon does not allow email delivery of AZW3 and address. Also note that Amazon does not allow email delivery of AZW3 and
new style (KF8) MOBI files. new style (KF8) MOBI files.
Even after doing this, you may have problems. One common source of problems is that some poorly designed antivirus Even after doing this, you may have problems. One common source of problems is that some poorly designed antivirus
programs block |app| from opening a connection to send email. Try adding an exclusion for |app| in your programs block calibre from opening a connection to send email. Try adding an exclusion for calibre in your
antivirus program. antivirus program.
.. note:: .. note::
Microsoft/Google can disable your account if you use it to send large Microsoft/Google can disable your account if you use it to send large
amounts of email. So, when using Hotmail/Gmail to send mail |app| automatically amounts of email. So, when using Hotmail/Gmail to send mail calibre automatically
restricts itself to sending one book every five minutes. If you don't mind restricts itself to sending one book every five minutes. If you don't mind
risking your account being blocked you can reduce this wait interval by going risking your account being blocked you can reduce this wait interval by going
to Preferences->Tweaks in |app|. to Preferences->Tweaks in calibre.
.. note:: .. note::
Google recently deliberately broke their email sending protocol (SMTP) support in Google recently deliberately broke their email sending protocol (SMTP) support in
@ -475,14 +475,14 @@ antivirus program.
`allow less secure apps as descibed here <https://support.google.com/accounts/answer/6010255>`_. `allow less secure apps as descibed here <https://support.google.com/accounts/answer/6010255>`_.
.. note:: .. note::
If you are concerned about giving |app| access to your email If you are concerned about giving calibre access to your email
account, simply create a new free email account with GMX or Hotmail account, simply create a new free email account with GMX or Hotmail
and use it only for |app|. and use it only for calibre.
Why is my device not detected in linux? Why is my device not detected in linux?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| needs your linux kernel to have been setup correctly to detect devices. If your devices are not detected, perform the following tests:: calibre needs your linux kernel to have been setup correctly to detect devices. If your devices are not detected, perform the following tests::
grep SYSFS_DEPRECATED /boot/config-`uname -r` grep SYSFS_DEPRECATED /boot/config-`uname -r`
@ -493,7 +493,7 @@ Also, ::
must return ``CONFIG_SCSI_MULTI_LUN=y``. If you don't see either, you have to recompile your kernel with the correct settings. must return ``CONFIG_SCSI_MULTI_LUN=y``. If you don't see either, you have to recompile your kernel with the correct settings.
My device is getting mounted read-only in linux, so |app| cannot connect to it? My device is getting mounted read-only in linux, so calibre cannot connect to it?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Linux kernels mount devices read-only when their filesystems have errors. You can repair the filesystem with:: Linux kernels mount devices read-only when their filesystems have errors. You can repair the filesystem with::
@ -506,7 +506,7 @@ will always be under /dev by examining the output of::
mount mount
Why does |app| not support collections on the Kindle or shelves on the Nook? Why does calibre not support collections on the Kindle or shelves on the Nook?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Neither the Kindle nor the Nook provide any way to manipulate collections over Neither the Kindle nor the Nook provide any way to manipulate collections over
@ -517,9 +517,9 @@ life is too short to be entering collections one by one on an e-ink screen :)
Note that in the case of the Kindle, there is a way to manipulate collections Note that in the case of the Kindle, there is a way to manipulate collections
via USB, but it requires that the Kindle be rebooted *every time* it is via USB, but it requires that the Kindle be rebooted *every time* it is
disconnected from the computer, for the changes to the collections to be disconnected from the computer, for the changes to the collections to be
recognized. As such, it is unlikely that any |app| developers will ever feel recognized. As such, it is unlikely that any calibre developers will ever feel
motivated enough to support it. There is however, a |app| plugin that allows motivated enough to support it. There is however, a calibre plugin that allows
you to create collections on your Kindle from the |app| metadata. It is you to create collections on your Kindle from the calibre metadata. It is
available `from here <http://www.mobileread.com/forums/showthread.php?t=244202>`_. available `from here <http://www.mobileread.com/forums/showthread.php?t=244202>`_.
.. note:: .. note::
@ -527,14 +527,14 @@ available `from here <http://www.mobileread.com/forums/showthread.php?t=244202>`
in their newer models, like the Kindle Touch and Kindle Fire, making even the in their newer models, like the Kindle Touch and Kindle Fire, making even the
above plugin useless, unless you root your Kindle and install custom firmware. above plugin useless, unless you root your Kindle and install custom firmware.
I am getting an error when I try to use |app| with my Kobo Touch/Glo/etc.? I am getting an error when I try to use calibre with my Kobo Touch/Glo/etc.?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Kobo has very buggy firmware. Connecting to it has been known to fail at The Kobo has very buggy firmware. Connecting to it has been known to fail at
random. Certain combinations of motherboard, USB ports/cables/hubs can random. Certain combinations of motherboard, USB ports/cables/hubs can
exacerbate this tendency to fail. If you are getting an error when connecting exacerbate this tendency to fail. If you are getting an error when connecting
to your touch with |app| try the following, each of which has solved the to your touch with calibre try the following, each of which has solved the
problem for *some* |app| users. problem for *some* calibre users.
* Connect the Kobo directly to your computer, not via USB Hub * Connect the Kobo directly to your computer, not via USB Hub
* Try a different USB cable and a different USB port on your computer * Try a different USB cable and a different USB port on your computer
@ -552,44 +552,44 @@ Library Management
:depth: 1 :depth: 1
:local: :local:
What formats does |app| read metadata from? What formats does calibre read metadata from?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| reads metadata from the following formats: CHM, LRF, PDF, LIT, RTF, OPF, MOBI, PRC, EPUB, FB2, IMP, RB, HTML. In addition it can write metadata to: LRF, RTF, OPF, EPUB, PDF, MOBI calibre reads metadata from the following formats: CHM, LRF, PDF, LIT, RTF, OPF, MOBI, PRC, EPUB, FB2, IMP, RB, HTML. In addition it can write metadata to: LRF, RTF, OPF, EPUB, PDF, MOBI
Where are the book files stored? Where are the book files stored?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When you first run |app|, it will ask you for a folder in which to store your books. Whenever you add a book to |app|, it will copy the book into that folder. Books in the folder are nicely arranged into sub-folders by Author and Title. Note that the contents of this folder are automatically managed by |app|, **do not** add any files/folders manually to this folder, as they may be automatically deleted. If you want to add a file associated to a particular book, use the top right area of :guilabel:`Edit metadata` dialog to do so. Then, |app| will automatically put that file into the correct folder and move it around when the title/author changes. When you first run calibre, it will ask you for a folder in which to store your books. Whenever you add a book to calibre, it will copy the book into that folder. Books in the folder are nicely arranged into sub-folders by Author and Title. Note that the contents of this folder are automatically managed by calibre, **do not** add any files/folders manually to this folder, as they may be automatically deleted. If you want to add a file associated to a particular book, use the top right area of :guilabel:`Edit metadata` dialog to do so. Then, calibre will automatically put that file into the correct folder and move it around when the title/author changes.
Metadata about the books is stored in the file ``metadata.db`` at the top level of the library folder This file is is a sqlite database. When backing up your library make sure you copy the entire folder and all its sub-folders. Metadata about the books is stored in the file ``metadata.db`` at the top level of the library folder This file is is a sqlite database. When backing up your library make sure you copy the entire folder and all its sub-folders.
The library folder and all it's contents make up what is called a |app| library. You can have multiple such libraries. To manage the libraries, click the |app| icon on the toolbar. You can create new libraries, remove/rename existing ones and switch between libraries easily. The library folder and all it's contents make up what is called a calibre library. You can have multiple such libraries. To manage the libraries, click the calibre icon on the toolbar. You can create new libraries, remove/rename existing ones and switch between libraries easily.
You can copy or move books between different libraries (once you have more than one library setup) by right clicking on a book and selecting the :guilabel:`Copy to library` action. You can copy or move books between different libraries (once you have more than one library setup) by right clicking on a book and selecting the :guilabel:`Copy to library` action.
How does |app| manage author names and sorting? How does calibre manage author names and sorting?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Author names are complex, especially across cultures, see `this note <http://www.w3.org/International/questions/qa-personal-names.en.php?changelang=en>`_ for some of complexities. |app| has a very flexible strategy for managing author names. The first thing to understand is that books and authors are separate entities in |app|. A book can have more than one author, and an author can have more than one book. You can manage the authors of a book by the edit metadata dialog. You can manage individual authors by right clicking on the author in the Tag Browser on the left of the main |app| screen and selecting :guilabel:`Manage authors`. Using this dialog you can change the name of an author and also how that name is sorted. This will automatically change the name of the author in all the books of that author. When a book has multiple authors, separate their names using the & character. Author names are complex, especially across cultures, see `this note <http://www.w3.org/International/questions/qa-personal-names.en.php?changelang=en>`_ for some of complexities. calibre has a very flexible strategy for managing author names. The first thing to understand is that books and authors are separate entities in calibre. A book can have more than one author, and an author can have more than one book. You can manage the authors of a book by the edit metadata dialog. You can manage individual authors by right clicking on the author in the Tag Browser on the left of the main calibre screen and selecting :guilabel:`Manage authors`. Using this dialog you can change the name of an author and also how that name is sorted. This will automatically change the name of the author in all the books of that author. When a book has multiple authors, separate their names using the & character.
Now coming to author name sorting: Now coming to author name sorting:
* When a new author is added to |app| (this happens whenever a book by a new author is added), |app| automatically computes a sort string for both the book and the author. * When a new author is added to calibre (this happens whenever a book by a new author is added), calibre automatically computes a sort string for both the book and the author.
* Authors in the Tag Browser are sorted by the sort value for the **authors**. Remember that this is different from the Author sort field for a book. * Authors in the Tag Browser are sorted by the sort value for the **authors**. Remember that this is different from the Author sort field for a book.
* By default, this sort algorithm assumes that the author name is in ``First name Last name`` format and generates a ``Last name, First name`` sort value. * By default, this sort algorithm assumes that the author name is in ``First name Last name`` format and generates a ``Last name, First name`` sort value.
* You can change this algorithm by going to Preferences->Tweaks and setting the :guilabel:`author_sort_copy_method` tweak. * You can change this algorithm by going to Preferences->Tweaks and setting the :guilabel:`author_sort_copy_method` tweak.
* You can force |app| to recalculate the author sort values for every author by right clicking on any author and selecting :guilabel:`Manage authors`, then pushing the `Recalculate all author sort values` button. Do this after you have set the author_sort_copy_method tweak to what you want. * You can force calibre to recalculate the author sort values for every author by right clicking on any author and selecting :guilabel:`Manage authors`, then pushing the `Recalculate all author sort values` button. Do this after you have set the author_sort_copy_method tweak to what you want.
* You can force |app| to recalculate the author sort values for all books by using the bulk metadata edit dialog (select all books and click edit metadata, check the `Automatically set author sort` checkbox, then press OK.) * You can force calibre to recalculate the author sort values for all books by using the bulk metadata edit dialog (select all books and click edit metadata, check the `Automatically set author sort` checkbox, then press OK.)
* When recalculating the author sort values for books, |app| uses the author sort values for each individual author. Therefore, ensure that the individual author sort values are correct before recalculating the books' author sort values. * When recalculating the author sort values for books, calibre uses the author sort values for each individual author. Therefore, ensure that the individual author sort values are correct before recalculating the books' author sort values.
* You can control whether the Tag Browser display authors using their names or their sort values by setting the :guilabel:`categories_use_field_for_author_name` tweak in Preferences->Tweaks * You can control whether the Tag Browser display authors using their names or their sort values by setting the :guilabel:`categories_use_field_for_author_name` tweak in Preferences->Tweaks
Note that you can set an individual author's sort value to whatever you want using :guilabel:`Manage authors`. This is useful when dealing with names that |app| will not get right, such as complex multi-part names like Miguel de Cervantes Saavedra or when dealing with Asian names like Sun Tzu. Note that you can set an individual author's sort value to whatever you want using :guilabel:`Manage authors`. This is useful when dealing with names that calibre will not get right, such as complex multi-part names like Miguel de Cervantes Saavedra or when dealing with Asian names like Sun Tzu.
With all this flexibility, it is possible to have |app| manage your author names however you like. For example, one common request is to have |app| display author names LN, FN. To do this, and if the note below does not apply to you, then: With all this flexibility, it is possible to have calibre manage your author names however you like. For example, one common request is to have calibre display author names LN, FN. To do this, and if the note below does not apply to you, then:
* Set the ``author_sort_copy_method`` tweak to ``copy`` as described above. * Set the ``author_sort_copy_method`` tweak to ``copy`` as described above.
* Restart calibre. Do not change any book metadata before doing the remaining steps. * Restart calibre. Do not change any book metadata before doing the remaining steps.
* Change all author names to LN, FN using the Manage authors dialog. * Change all author names to LN, FN using the Manage authors dialog.
* After you have changed all the authors, press the `Recalculate all author sort values` button. * After you have changed all the authors, press the `Recalculate all author sort values` button.
* Press OK, at which point |app| will change the authors in all your books. This can take a while. * Press OK, at which point calibre will change the authors in all your books. This can take a while.
.. note:: .. note::
@ -598,13 +598,13 @@ With all this flexibility, it is possible to have |app| manage your author names
* restart calibre. Do not change any book metadata before doing the remaining steps. * restart calibre. Do not change any book metadata before doing the remaining steps.
* open the Manage authors dialog. Press the ``copy all author sort values to author`` button. * open the Manage authors dialog. Press the ``copy all author sort values to author`` button.
* Check through the authors to be sure you are happy. You can still press Cancel to abandon the changes. Once you press OK, there is no undo. * Check through the authors to be sure you are happy. You can still press Cancel to abandon the changes. Once you press OK, there is no undo.
* Press OK, at which point |app| will change the authors in all your books. This can take a while. * Press OK, at which point calibre will change the authors in all your books. This can take a while.
Why doesn't |app| let me store books in my own directory structure? Why doesn't calibre let me store books in my own directory structure?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The whole point of |app|'s library management features is that they provide a search and sort based interface for locating books that is *much* more efficient than any possible directory scheme you could come up with for your collection. Indeed, once you become comfortable using |app|'s interface to find, sort and browse your collection, you wont ever feel the need to hunt through the files on your disk to find a book again. By managing books in its own directory structure of Author -> Title -> Book files, |app| is able to achieve a high level of reliability and standardization. To illustrate why a search/tagging based interface is superior to folders, consider the following. Suppose your book collection is nicely sorted into folders with the following scheme:: The whole point of calibre's library management features is that they provide a search and sort based interface for locating books that is *much* more efficient than any possible directory scheme you could come up with for your collection. Indeed, once you become comfortable using calibre's interface to find, sort and browse your collection, you wont ever feel the need to hunt through the files on your disk to find a book again. By managing books in its own directory structure of Author -> Title -> Book files, calibre is able to achieve a high level of reliability and standardization. To illustrate why a search/tagging based interface is superior to folders, consider the following. Suppose your book collection is nicely sorted into folders with the following scheme::
Genre -> Author -> Series -> ReadStatus Genre -> Author -> Series -> ReadStatus
@ -612,19 +612,19 @@ Now this makes it very easy to find for example all science fiction books by Isa
ReadStatus -> Genre -> Author -> Series ReadStatus -> Genre -> Author -> Series
In |app|, you would instead use tags to mark genre and read status and then just use a simple search query like ``tag:scifi and not tag:read``. |app| even has a nice graphical interface, so you don't need to learn its search language instead you can just click on tags to include or exclude them from the search. In calibre, you would instead use tags to mark genre and read status and then just use a simple search query like ``tag:scifi and not tag:read``. calibre even has a nice graphical interface, so you don't need to learn its search language instead you can just click on tags to include or exclude them from the search.
To those of you that claim that you need access to the filesystem to so that you can have access to your books over the network, |app| has an excellent content server that gives you access to your calibre library over the net. To those of you that claim that you need access to the filesystem to so that you can have access to your books over the network, calibre has an excellent content server that gives you access to your calibre library over the net.
If you are worried that someday |app| will cease to be developed, leaving all your books marooned in its folder structure, explore the powerful "Save to Disk" feature in |app| that lets you export all your files into a folder structure of arbitrary complexity based on their metadata. If you are worried that someday calibre will cease to be developed, leaving all your books marooned in its folder structure, explore the powerful "Save to Disk" feature in calibre that lets you export all your files into a folder structure of arbitrary complexity based on their metadata.
Finally, the reason there are numbers at the end of every title folder, is for *robustness*. That number is the id number of the book record in the |app| database. The presence of the number allows you to have multiple records with the same title and author names. It is also part of what allows |app| to magically regenerate the database with all metadata if the database file gets corrupted. Given that |app|'s mission is to get you to stop storing metadata in filenames and stop using the filesystem to find things, the increased robustness afforded by the id numbers is well worth the uglier folder names. Finally, the reason there are numbers at the end of every title folder, is for *robustness*. That number is the id number of the book record in the calibre database. The presence of the number allows you to have multiple records with the same title and author names. It is also part of what allows calibre to magically regenerate the database with all metadata if the database file gets corrupted. Given that calibre's mission is to get you to stop storing metadata in filenames and stop using the filesystem to find things, the increased robustness afforded by the id numbers is well worth the uglier folder names.
If you are still not convinced, then I'm afraid |app| is not for you. Look elsewhere for your book cataloguing needs. Just so we're clear, **this is not going to change**. Kindly do not contact us in an attempt to get us to change this. If you are still not convinced, then I'm afraid calibre is not for you. Look elsewhere for your book cataloguing needs. Just so we're clear, **this is not going to change**. Kindly do not contact us in an attempt to get us to change this.
Why doesn't |app| have a column for foo? Why doesn't calibre have a column for foo?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| is designed to have columns for the most frequently and widely used fields. In addition, you can add any columns you like. Columns can be added via :guilabel:`Preferences->Interface->Add your own columns`. calibre is designed to have columns for the most frequently and widely used fields. In addition, you can add any columns you like. Columns can be added via :guilabel:`Preferences->Interface->Add your own columns`.
Watch the tutorial `UI Power tips <http://calibre-ebook.com/demo#tutorials>`_ to learn how to create your own columns. Watch the tutorial `UI Power tips <http://calibre-ebook.com/demo#tutorials>`_ to learn how to create your own columns.
You can also create "virtual columns" that contain combinations of the metadata from other columns. In the add column dialog use the :guilabel:`Quick create` links to easily create columns to show the book ISBN, formats or the time the book was last modified. For more details, see :ref:`templatelangcalibre`. You can also create "virtual columns" that contain combinations of the metadata from other columns. In the add column dialog use the :guilabel:`Quick create` links to easily create columns to show the book ISBN, formats or the time the book was last modified. For more details, see :ref:`templatelangcalibre`.
@ -634,54 +634,54 @@ Can I have a column showing the formats or the ISBN?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Yes, you can. Follow the instructions in the answer above for adding custom columns. Yes, you can. Follow the instructions in the answer above for adding custom columns.
How do I move my |app| library from one computer to another? How do I move my calibre library from one computer to another?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Simply copy the |app| library folder from the old to the new computer. You can Simply copy the calibre library folder from the old to the new computer. You can
find out what the library folder is by clicking the calibre icon in the find out what the library folder is by clicking the calibre icon in the
toolbar. The very first item is the path to the library folder. Now on the new toolbar. The very first item is the path to the library folder. Now on the new
computer, start |app| for the first time. It will run the Welcome Wizard asking computer, start calibre for the first time. It will run the Welcome Wizard asking
you for the location of the |app| library. Point it to the previously copied you for the location of the calibre library. Point it to the previously copied
folder. If the computer you are transferring to already has a calibre folder. If the computer you are transferring to already has a calibre
installation, then the Welcome wizard wont run. In that case, right-click the installation, then the Welcome wizard wont run. In that case, right-click the
|app| icon in the tooolbar and point it to the newly copied directory. You will calibre icon in the tooolbar and point it to the newly copied directory. You will
now have two |app| libraries on your computer and you can switch between them now have two calibre libraries on your computer and you can switch between them
by clicking the |app| icon on the toolbar. Transferring your library in this by clicking the calibre icon on the toolbar. Transferring your library in this
manner preserver all your metadata, tags, custom columns, etc. manner preserver all your metadata, tags, custom columns, etc.
Note that if you are transferring between different types of computers (for Note that if you are transferring between different types of computers (for
example Windows to OS X) then after doing the above you should also right-click example Windows to OS X) then after doing the above you should also right-click
the |app| icon on the tool bar, select Library Maintenance and run the Check the calibre icon on the tool bar, select Library Maintenance and run the Check
Library action. It will warn you about any problems in your library, which you Library action. It will warn you about any problems in your library, which you
should fix by hand. should fix by hand.
.. note:: A |app| library is just a folder which contains all the book files and their metadata. All the metadata is stored in a single file called metadata.db, in the top level folder. If this file gets corrupted, you may see an empty list of books in |app|. In this case you can ask |app| to restore your books by doing a right-click on the |app| icon in the toolbar and selecting Library Maintenance->Restore database .. note:: A calibre library is just a folder which contains all the book files and their metadata. All the metadata is stored in a single file called metadata.db, in the top level folder. If this file gets corrupted, you may see an empty list of books in calibre. In this case you can ask calibre to restore your books by doing a right-click on the calibre icon in the toolbar and selecting Library Maintenance->Restore database
The list of books in |app| is blank! The list of books in calibre is blank!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to understand why that happened, you have to understand what a |app| In order to understand why that happened, you have to understand what a calibre
library is. At the most basic level, a |app| library is just a folder. Whenever library is. At the most basic level, a calibre library is just a folder. Whenever
you add a book to |app|, that book's files are copied into this folder you add a book to calibre, that book's files are copied into this folder
(arranged into sub folders by author and title). Inside the |app| library (arranged into sub folders by author and title). Inside the calibre library
folder, at the top level, you will see a file called metadata.db. This file is folder, at the top level, you will see a file called metadata.db. This file is
where |app| stores the metadata like title/author/rating/tags etc. for *every* where calibre stores the metadata like title/author/rating/tags etc. for *every*
book in your |app| library. The list of books that |app| displays is created by book in your calibre library. The list of books that calibre displays is created by
reading the contents of this metadata.db file. reading the contents of this metadata.db file.
There can be two reasons why |app| is showing a empty list of books: There can be two reasons why calibre is showing a empty list of books:
* Your |app| library folder changed its location. This can happen if it was * Your calibre library folder changed its location. This can happen if it was
on an external disk and the drive letter for that disk changed. Or if you on an external disk and the drive letter for that disk changed. Or if you
accidentally moved the folder. In this case, |app| cannot find its library accidentally moved the folder. In this case, calibre cannot find its library
and so starts up with an empty library instead. To remedy this, do a and so starts up with an empty library instead. To remedy this, do a
right-click on the |app| icon in the |app| toolbar and select Switch/create right-click on the calibre icon in the calibre toolbar and select Switch/create
library. Click the little blue icon to select the new location of your library. Click the little blue icon to select the new location of your
|app| library and click OK. calibre library and click OK.
* Your metadata.db file was deleted/corrupted. In this case, you can ask * Your metadata.db file was deleted/corrupted. In this case, you can ask
|app| to rebuild the metadata.db from its backups. Right click the |app| calibre to rebuild the metadata.db from its backups. Right click the calibre
icon in the |app| toolbar and select Library maintenance->Restore database. icon in the calibre toolbar and select Library maintenance->Restore database.
|app| will automatically rebuild metadata.db. calibre will automatically rebuild metadata.db.
I am getting errors with my calibre library on a networked drive/NAS? I am getting errors with my calibre library on a networked drive/NAS?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -689,27 +689,27 @@ I am getting errors with my calibre library on a networked drive/NAS?
**Do not put your calibre library on a networked drive**. **Do not put your calibre library on a networked drive**.
A filesystem is a complex beast. Most network filesystems lack various A filesystem is a complex beast. Most network filesystems lack various
filesystem features that |app| uses. Some dont support file locking, some dont filesystem features that calibre uses. Some dont support file locking, some dont
support hardlinking, some are just flaky. Additionally, |app| is a single user support hardlinking, some are just flaky. Additionally, calibre is a single user
application, if you accidentally run two copies of |app| on the same networked application, if you accidentally run two copies of calibre on the same networked
library, bad things will happen. Finally, different OSes impose different library, bad things will happen. Finally, different OSes impose different
limitations on filesystems, so if you share your networked drive across OSes, limitations on filesystems, so if you share your networked drive across OSes,
once again, bad things *will happen*. once again, bad things *will happen*.
Consider using the |app| Content Server to make your books available on other Consider using the calibre Content Server to make your books available on other
computers. Run |app| on a single computer and access it via the Content Server computers. Run calibre on a single computer and access it via the Content Server
or a Remote Desktop solution. or a Remote Desktop solution.
If you must share the actual library, use a file syncing tool like If you must share the actual library, use a file syncing tool like
DropBox or rsync instead of a networked drive. If you are DropBox or rsync instead of a networked drive. If you are
using a file-syncing tool it is **essential** that you make sure that both using a file-syncing tool it is **essential** that you make sure that both
|app| and the file syncing tool do not try to access the |app| library at the calibre and the file syncing tool do not try to access the calibre library at the
same time. In other words, **do not** run the file syncing tool and |app| at same time. In other words, **do not** run the file syncing tool and calibre at
the same time. the same time.
Even with these tools there is danger of data corruption/loss, so only do this Even with these tools there is danger of data corruption/loss, so only do this
if you are willing to live with that risk. In particular, be aware that if you are willing to live with that risk. In particular, be aware that
**Google Drive** is incompatible with |app|, if you put your |app| library in **Google Drive** is incompatible with calibre, if you put your calibre library in
Google Drive, **you will suffer data loss**. See `this thread Google Drive, **you will suffer data loss**. See `this thread
<http://www.mobileread.com/forums/showthread.php?t=205581>`_ for details. <http://www.mobileread.com/forums/showthread.php?t=205581>`_ for details.
@ -722,9 +722,9 @@ Miscellaneous
:local: :local:
I want |app| to download news from my favorite news website. I want calibre to download news from my favorite news website.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are reasonably proficient with computers, you can teach |app| to download news from any website of your choosing. To learn how to do this see :ref:`news`. If you are reasonably proficient with computers, you can teach calibre to download news from any website of your choosing. To learn how to do this see :ref:`news`.
Otherwise, you can request a particular news site by posting in the `calibre Recipes forum <http://www.mobileread.com/forums/forumdisplay.php?f=228>`_. Otherwise, you can request a particular news site by posting in the `calibre Recipes forum <http://www.mobileread.com/forums/forumdisplay.php?f=228>`_.
@ -737,25 +737,25 @@ Take your pick:
* A tribute to the SONY Librie which was the first e-ink based ebook reader * A tribute to the SONY Librie which was the first e-ink based ebook reader
* My wife chose it ;-) * My wife chose it ;-)
|app| is pronounced as cal-i-ber *not* ca-li-bre. If you're wondering, |app| is the British/commonwealth spelling for caliber. Being Indian, that's the natural spelling for me. calibre is pronounced as cal-i-ber *not* ca-li-bre. If you're wondering, calibre is the British/commonwealth spelling for caliber. Being Indian, that's the natural spelling for me.
Why does |app| show only some of my fonts on OS X? Why does calibre show only some of my fonts on OS X?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| embeds fonts in ebook files it creates. Ebook files support embedding calibre embeds fonts in ebook files it creates. Ebook files support embedding
only TrueType and OpenType (.ttf and .otf) fonts. Most fonts on OS X systems only TrueType and OpenType (.ttf and .otf) fonts. Most fonts on OS X systems
are in .dfont format, thus they cannot be embedded. |app| shows only TrueType are in .dfont format, thus they cannot be embedded. calibre shows only TrueType
and OpenType fonts found on your system. You can obtain many such fonts on the and OpenType fonts found on your system. You can obtain many such fonts on the
web. Simply download the .ttf/.otf files and add them to the Library/Fonts web. Simply download the .ttf/.otf files and add them to the Library/Fonts
directory in your home directory. directory in your home directory.
|app| is not starting on Windows? calibre is not starting on Windows?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There can be several causes for this: There can be several causes for this:
* If you are on Windows XP, or on a computer with a processor that does not * If you are on Windows XP, or on a computer with a processor that does not
support SSE2 (such as AMD processors from before 2003) try installing support SSE2 (such as AMD processors from before 2003) try installing
|app| `version 1.48 <http://download.calibre-ebook.com/1.48.0/>`_. |app| calibre `version 1.48 <http://download.calibre-ebook.com/1.48.0/>`_. calibre
2.0 and newer use Qt 5 which is known to be incompatible with Windows XP 2.0 and newer use Qt 5 which is known to be incompatible with Windows XP
machines, and requires SSE2. Simply un-install calibre and then install machines, and requires SSE2. Simply un-install calibre and then install
version 1.48, doing so will not affect your books/settings. version 1.48, doing so will not affect your books/settings.
@ -782,48 +782,48 @@ If it still wont launch, start a command prompt (press the windows key and R; th
Post any output you see in a help message on the `Forum <http://www.mobileread.com/forums/forumdisplay.php?f=166>`_. Post any output you see in a help message on the `Forum <http://www.mobileread.com/forums/forumdisplay.php?f=166>`_.
|app| freezes/crashes occasionally? calibre freezes/crashes occasionally?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are several possible things I know of, that can cause this: There are several possible things I know of, that can cause this:
* You recently connected an external monitor or TV to your computer. In * You recently connected an external monitor or TV to your computer. In
this case, whenever |app| opens a new window like the edit metadata this case, whenever calibre opens a new window like the edit metadata
window or the conversion dialog, it appears on the second monitor where window or the conversion dialog, it appears on the second monitor where
you dont notice it and so you think |app| has frozen. Disconnect your you dont notice it and so you think calibre has frozen. Disconnect your
second monitor and restart calibre. second monitor and restart calibre.
* If you use RoboForm, it is known to cause |app| to crash. Add |app| to * If you use RoboForm, it is known to cause calibre to crash. Add calibre to
the blacklist of programs inside RoboForm to fix this. Or uninstall the blacklist of programs inside RoboForm to fix this. Or uninstall
RoboForm. RoboForm.
* The Logitech SetPoint Settings application causes random crashes in * The Logitech SetPoint Settings application causes random crashes in
|app| when it is open. Close it before starting |app|. calibre when it is open. Close it before starting calibre.
* Constant Guard Protection by Xfinity causes crashes in |app|. You have to * Constant Guard Protection by Xfinity causes crashes in calibre. You have to
manually allow |app| in it or uninstall Constant Guard Protection. manually allow calibre in it or uninstall Constant Guard Protection.
* Spybot - Search & Destroy blocks |app| from accessing its temporary files * Spybot - Search & Destroy blocks calibre from accessing its temporary files
breaking viewing and converting of books. breaking viewing and converting of books.
* You are using a Wacom branded USB mouse. There is an incompatibility between * You are using a Wacom branded USB mouse. There is an incompatibility between
Wacom mice and the graphics toolkit |app| uses. Try using a non-Wacom Wacom mice and the graphics toolkit calibre uses. Try using a non-Wacom
mouse. mouse.
* On some 64 bit versions of Windows there are security software/settings * On some 64 bit versions of Windows there are security software/settings
that prevent 64-bit |app| from working properly. If you are using the 64-bit that prevent 64-bit calibre from working properly. If you are using the 64-bit
version of |app| try switching to the 32-bit version. version of calibre try switching to the 32-bit version.
* If the crashes happen specifically when you are using a file open dialog, * If the crashes happen specifically when you are using a file open dialog,
like clicking on the Add Books button or the Save to Disk button, then like clicking on the Add Books button or the Save to Disk button, then
you may have an issue with the windows file open dialogs on your you may have an issue with the windows file open dialogs on your
computer. Some |app| users have reported that uninstalling the SpiderOak computer. Some calibre users have reported that uninstalling the SpiderOak
encrypted backup software also fixes these crashes. If you do not wish to encrypted backup software also fixes these crashes. If you do not wish to
uninstall SpiderOak, you can also turn off "Enable OS integration" in the uninstall SpiderOak, you can also turn off "Enable OS integration" in the
SpiderOak preferences. SpiderOak preferences.
If none of the above apply to you, then there is some other program on your If none of the above apply to you, then there is some other program on your
computer that is interfering with |app|. First reboot your computer in safe computer that is interfering with calibre. First reboot your computer in safe
mode, to have as few running programs as possible, and see if the crashes still mode, to have as few running programs as possible, and see if the crashes still
happen. If they do not, then you know it is some program causing the problem. happen. If they do not, then you know it is some program causing the problem.
The most likely such culprit is a program that modifies other programs' The most likely such culprit is a program that modifies other programs'
@ -860,14 +860,14 @@ some functionality, such as drag and drop to not work.
Finally, some users have reported that disabling UAC fixes the problem. Finally, some users have reported that disabling UAC fixes the problem.
|app| is not starting on OS X? calibre is not starting on OS X?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
One common cause of failures on OS X is the use of accessibility technologies that are incompatible with the graphics toolkit |app| uses. One common cause of failures on OS X is the use of accessibility technologies that are incompatible with the graphics toolkit calibre uses.
Try turning off VoiceOver if you have it on. Also go to System Preferences->System->Universal Access and turn off the setting for enabling Try turning off VoiceOver if you have it on. Also go to System Preferences->System->Universal Access and turn off the setting for enabling
access for assistive devices in all the tabs. access for assistive devices in all the tabs.
You can obtain debug output about why |app| is not starting by running `Console.app`. Debug output will You can obtain debug output about why calibre is not starting by running `Console.app`. Debug output will
be printed to it. If the debug output contains a line that looks like:: be printed to it. If the debug output contains a line that looks like::
Qt: internal: -108: Error ATSUMeasureTextImage text/qfontengine_mac.mm Qt: internal: -108: Error ATSUMeasureTextImage text/qfontengine_mac.mm
@ -882,11 +882,11 @@ menu, choose "Validate fonts".
I downloaded the installer, but it is not working? I downloaded the installer, but it is not working?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Downloading from the Internet can sometimes result in a corrupted download. If the |app| installer you downloaded is not opening, try downloading it again. If re-downloading it does not work, download it from `an alternate location <http://sourceforge.net/projects/calibre/files/>`_. If the installer still doesn't work, then something on your computer is preventing it from running. Downloading from the Internet can sometimes result in a corrupted download. If the calibre installer you downloaded is not opening, try downloading it again. If re-downloading it does not work, download it from `an alternate location <http://sourceforge.net/projects/calibre/files/>`_. If the installer still doesn't work, then something on your computer is preventing it from running.
* Try temporarily disabling your antivirus program (Microsoft Security Essentials, or Kaspersky or Norton or McAfee or whatever). This is most likely the culprit if the upgrade process is hanging in the middle. * Try temporarily disabling your antivirus program (Microsoft Security Essentials, or Kaspersky or Norton or McAfee or whatever). This is most likely the culprit if the upgrade process is hanging in the middle.
* Try rebooting your computer and running a registry cleaner like `Wise registry cleaner <http://www.wisecleaner.com>`_. * Try rebooting your computer and running a registry cleaner like `Wise registry cleaner <http://www.wisecleaner.com>`_.
* Try a clean install. That is, uninstall |app|, delete :file:`C:\\Program Files\\Calibre2` (or wherever you previously chose to install |app|). Then re-install |app|. Note that uninstalling does not touch your books or settings. * Try a clean install. That is, uninstall calibre, delete :file:`C:\\Program Files\\Calibre2` (or wherever you previously chose to install calibre). Then re-install calibre. Note that uninstalling does not touch your books or settings.
* Try downloading the installer with an alternate browser. For example if you are using Internet Explorer, try using Firefox or Chrome instead. * Try downloading the installer with an alternate browser. For example if you are using Internet Explorer, try using Firefox or Chrome instead.
* If you get an error about a missing DLL on windows, then most likely, the * If you get an error about a missing DLL on windows, then most likely, the
permissions on your temporary folder are incorrect. Go to the folder permissions on your temporary folder are incorrect. Go to the folder
@ -897,42 +897,42 @@ Downloading from the Internet can sometimes result in a corrupted download. If t
If you still cannot get the installer to work and you are on windows, you can use the `calibre portable install <http://calibre-ebook.com/download_portable>`_, which does not need an installer (it is just a zip file). If you still cannot get the installer to work and you are on windows, you can use the `calibre portable install <http://calibre-ebook.com/download_portable>`_, which does not need an installer (it is just a zip file).
My antivirus program claims |app| is a virus/trojan? My antivirus program claims calibre is a virus/trojan?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The first thing to check is that you are downloading |app| from the official The first thing to check is that you are downloading calibre from the official
website: `<http://calibre-ebook.com/download>`_. Make sure you are clicking the website: `<http://calibre-ebook.com/download>`_. Make sure you are clicking the
download links on the left, not the advertisements on the right. |app| is a download links on the left, not the advertisements on the right. calibre is a
very popular program and unscrupulous people try to setup websites offering it very popular program and unscrupulous people try to setup websites offering it
for download to fool the unwary. for download to fool the unwary.
If you have the official download and your antivirus program is still claiming If you have the official download and your antivirus program is still claiming
|app| is a virus, then, your antivirus program is wrong. Antivirus programs use calibre is a virus, then, your antivirus program is wrong. Antivirus programs use
heuristics, patterns of code that "look suspicious" to detect viruses. It's heuristics, patterns of code that "look suspicious" to detect viruses. It's
rather like racial profiling. |app| is a completely open source product. You rather like racial profiling. calibre is a completely open source product. You
can actually browse the source code yourself (or hire someone to do it for you) can actually browse the source code yourself (or hire someone to do it for you)
to verify that it is not a virus. Please report the false identification to to verify that it is not a virus. Please report the false identification to
whatever company you buy your antivirus software from. If the antivirus program whatever company you buy your antivirus software from. If the antivirus program
is preventing you from downloading/installing |app|, disable it temporarily, is preventing you from downloading/installing calibre, disable it temporarily,
install |app| and then re-enable it. install calibre and then re-enable it.
How do I backup |app|? How do I backup calibre?
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
The most important thing to backup is the |app| library folder, that contains all your books and metadata. This is the folder you chose for your |app| library when you ran |app| for the first time. You can get the path to the library folder by clicking the |app| icon on the main toolbar. You must backup this complete folder with all its files and sub-folders. The most important thing to backup is the calibre library folder, that contains all your books and metadata. This is the folder you chose for your calibre library when you ran calibre for the first time. You can get the path to the library folder by clicking the calibre icon on the main toolbar. You must backup this complete folder with all its files and sub-folders.
You can switch |app| to using a backed up library folder by simply clicking the |app| icon on the toolbar and choosing your backup library folder. A backed up library folder backs up your custom columns and saved searches as well as all your books and metadata. You can switch calibre to using a backed up library folder by simply clicking the calibre icon on the toolbar and choosing your backup library folder. A backed up library folder backs up your custom columns and saved searches as well as all your books and metadata.
If you want to backup the |app| configuration/plugins, you have to backup the config directory. You can find this config directory via :guilabel:`Preferences->Miscellaneous`. Note that restoring configuration directories is not officially supported, but should work in most cases. Just copy the contents of the backup directory into the current configuration directory to restore. If you want to backup the calibre configuration/plugins, you have to backup the config directory. You can find this config directory via :guilabel:`Preferences->Miscellaneous`. Note that restoring configuration directories is not officially supported, but should work in most cases. Just copy the contents of the backup directory into the current configuration directory to restore.
How do I use purchased EPUB books with |app| (or what do I do with .acsm files)? How do I use purchased EPUB books with calibre (or what do I do with .acsm files)?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most purchased EPUB books have `DRM <http://drmfree.calibre-ebook.com/about#drm>`_. This prevents |app| from opening them. You can still use |app| to store and transfer them to your ebook reader. First, you must authorize your reader on a windows machine with Adobe Digital Editions. Once this is done, EPUB books transferred with |app| will work fine on your reader. When you purchase an epub book from a website, you will get an ".acsm" file. This file should be opened with Adobe Digital Editions, which will then download the actual ".epub" ebook. The ebook file will be stored in the folder "My Digital Editions", from where you can add it to |app|. Most purchased EPUB books have `DRM <http://drmfree.calibre-ebook.com/about#drm>`_. This prevents calibre from opening them. You can still use calibre to store and transfer them to your ebook reader. First, you must authorize your reader on a windows machine with Adobe Digital Editions. Once this is done, EPUB books transferred with calibre will work fine on your reader. When you purchase an epub book from a website, you will get an ".acsm" file. This file should be opened with Adobe Digital Editions, which will then download the actual ".epub" ebook. The ebook file will be stored in the folder "My Digital Editions", from where you can add it to calibre.
I am getting a "Permission Denied" error? I am getting a "Permission Denied" error?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A permission denied error can occur because of many possible reasons, none of them having anything to do with |app|. A permission denied error can occur because of many possible reasons, none of them having anything to do with calibre.
* You can get permission denied errors if you are using an SD card with write protect enabled. * You can get permission denied errors if you are using an SD card with write protect enabled.
* If you, or some program you used changed the file permissions of the files in question to read only. * If you, or some program you used changed the file permissions of the files in question to read only.
@ -941,7 +941,7 @@ A permission denied error can occur because of many possible reasons, none of th
* If your file is open in another program. * If your file is open in another program.
* If the file resides on a device, you may have reached the limit of a maximum of 256 files in the root of the device. In this case you need to reformat the device/sd card referered to in the error message with a FAT32 filesystem, or delete some files from the SD card/device memory. * If the file resides on a device, you may have reached the limit of a maximum of 256 files in the root of the device. In this case you need to reformat the device/sd card referered to in the error message with a FAT32 filesystem, or delete some files from the SD card/device memory.
You will need to fix the underlying cause of the permissions error before resuming to use |app|. Read the error message carefully, see what file it points to and fix the permissions on that file or its containing folders. You will need to fix the underlying cause of the permissions error before resuming to use calibre. Read the error message carefully, see what file it points to and fix the permissions on that file or its containing folders.
Can I have the comment metadata show up on my reader? Can I have the comment metadata show up on my reader?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -950,60 +950,60 @@ Most readers do not support this. You should complain to the manufacturer about
Another alternative is to create a catalog in ebook form containing a listing of all the books in your calibre library, with their metadata. Click-and-hold the convert button to access the catalog creation tool. And before you ask, no you cannot have the catalog "link directly to" books on your reader. Another alternative is to create a catalog in ebook form containing a listing of all the books in your calibre library, with their metadata. Click-and-hold the convert button to access the catalog creation tool. And before you ask, no you cannot have the catalog "link directly to" books on your reader.
How do I get |app| to use my HTTP proxy? How do I get calibre to use my HTTP proxy?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, |app| uses whatever proxy settings are set in your OS. Sometimes these are incorrect, for example, on windows if you don't use Internet Explorer then the proxy settings may not be up to date. You can tell |app| to use a particular proxy server by setting the http_proxy environment variable. The format of the variable is: http://username:password@servername you should ask your network admin to give you the correct value for this variable. Note that |app| only supports HTTP proxies not SOCKS proxies. You can see the current proxies used by |app| in Preferences->Miscellaneous. By default, calibre uses whatever proxy settings are set in your OS. Sometimes these are incorrect, for example, on windows if you don't use Internet Explorer then the proxy settings may not be up to date. You can tell calibre to use a particular proxy server by setting the http_proxy environment variable. The format of the variable is: http://username:password@servername you should ask your network admin to give you the correct value for this variable. Note that calibre only supports HTTP proxies not SOCKS proxies. You can see the current proxies used by calibre in Preferences->Miscellaneous.
I want some feature added to |app|. What can I do? I want some feature added to calibre. What can I do?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You have two choices: You have two choices:
1. Create a patch by hacking on |app| and send it to me for review and inclusion. See `Development <http://calibre-ebook.com/get-involved>`_. 1. Create a patch by hacking on calibre and send it to me for review and inclusion. See `Development <http://calibre-ebook.com/get-involved>`_.
2. `Open a bug requesting the feature <http://calibre-ebook.com/bugs>`_ . Remember that while you may think your feature request is extremely important/essential, |app| developers might not agree. Fortunately, |app| is open source, which means you always have the option of implementing your feature yourself, or hiring someone to do it for you. Furthermore, |app| has a comprehensive plugin architecture, so you might be able to develop your feature as a plugin, see :ref:`pluginstutorial`. 2. `Open a bug requesting the feature <http://calibre-ebook.com/bugs>`_ . Remember that while you may think your feature request is extremely important/essential, calibre developers might not agree. Fortunately, calibre is open source, which means you always have the option of implementing your feature yourself, or hiring someone to do it for you. Furthermore, calibre has a comprehensive plugin architecture, so you might be able to develop your feature as a plugin, see :ref:`pluginstutorial`.
Why doesn't |app| have an automatic update? Why doesn't calibre have an automatic update?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For many reasons: For many reasons:
* *There is no need to update every week*. If you are happy with how |app| * *There is no need to update every week*. If you are happy with how calibre
works turn off the update notification and be on your merry way. Check back works turn off the update notification and be on your merry way. Check back
to see if you want to update once a year or so. There is a check box to to see if you want to update once a year or so. There is a check box to
turn off the update notification, on the update notification itself. turn off the update notification, on the update notification itself.
* |app| downloads currently use `about 100TB of bandwidth a month * calibre downloads currently use `about 100TB of bandwidth a month
<http://status.calibre-ebook.com/downloads>`_. Implementing automatic <http://status.calibre-ebook.com/downloads>`_. Implementing automatic
updates would greatly increase that and end up costing thousands of dollars updates would greatly increase that and end up costing thousands of dollars
a month, which someone has to pay. And |app| is currently growing at `half a month, which someone has to pay. And calibre is currently growing at `half
a million new installs a month <https://status.calibre-ebook.com>`_. a million new installs a month <https://status.calibre-ebook.com>`_.
* If I implement a dialog that downloads the update and launches it, instead * If I implement a dialog that downloads the update and launches it, instead
of going to the website as it does now, that would save the most ardent of going to the website as it does now, that would save the most ardent
|app| updater, *at most five clicks a week*. There are far higher priority calibre updater, *at most five clicks a week*. There are far higher priority
things to do in |app| development. things to do in calibre development.
* If you really, really hate downloading |app| every week but still want to * If you really, really hate downloading calibre every week but still want to
be up to the latest, I encourage you to run from source, which makes be up to the latest, I encourage you to run from source, which makes
updating trivial. Instructions are :ref:`available here <develop>`. updating trivial. Instructions are :ref:`available here <develop>`.
How is |app| licensed? How is calibre licensed?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|app| is licensed under the GNU General Public License v3 (an open source license). This means that you are free to redistribute |app| as long as you make the source code available. So if you want to put |app| on a CD with your product, you must also put the |app| source code on the CD. The source code is available `for download <http://download.calibre-ebook.com>`_. You are free to use the results of conversions from |app| however you want. You cannot use either code or libraries from |app| in your software without making your software open source. For details, see `The GNU GPL v3 <http://www.gnu.org/licenses/gpl.html>`_. calibre is licensed under the GNU General Public License v3 (an open source license). This means that you are free to redistribute calibre as long as you make the source code available. So if you want to put calibre on a CD with your product, you must also put the calibre source code on the CD. The source code is available `for download <http://download.calibre-ebook.com>`_. You are free to use the results of conversions from calibre however you want. You cannot use either code or libraries from calibre in your software without making your software open source. For details, see `The GNU GPL v3 <http://www.gnu.org/licenses/gpl.html>`_.
How do I run calibre from my USB stick? How do I run calibre from my USB stick?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A portable version of calibre is available `here <http://calibre-ebook.com/download_portable>`_. A portable version of calibre is available `here <http://calibre-ebook.com/download_portable>`_.
How do I run parts of |app| like news download and the content server on my own linux server? How do I run parts of calibre like news download and the content server on my own linux server?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First, you must install |app| onto your linux server. If your server is using a modern linux distro, you should have no problems installing |app| onto it. First, you must install calibre onto your linux server. If your server is using a modern linux distro, you should have no problems installing calibre onto it.
.. note:: .. note::
If you bought into the notion that a real server must run a decade old version of Debian, then you will have to jump through a few hoops. First, compile a newer version of glibc (>= 2.10) on your server from source. Then get the |app| linux binary tarball from the |app| google code page for your server architecture. Extract it into :file:`/opt/calibre`. Put your previously compiled glibc into :file:`/opt/calibre` as :file:`libc.so.6`. You can now run the calibre binaries from :file:`/opt/calibre`. If you bought into the notion that a real server must run a decade old version of Debian, then you will have to jump through a few hoops. First, compile a newer version of glibc (>= 2.10) on your server from source. Then get the calibre linux binary tarball from the calibre google code page for your server architecture. Extract it into :file:`/opt/calibre`. Put your previously compiled glibc into :file:`/opt/calibre` as :file:`libc.so.6`. You can now run the calibre binaries from :file:`/opt/calibre`.
You can run the |app| server via the command:: You can run the calibre server via the command::
/opt/calibre/calibre-server --with-library /path/to/the/library/you/want/to/share /opt/calibre/calibre-server --with-library /path/to/the/library/you/want/to/share
@ -1019,11 +1019,11 @@ You can email downloaded news with the command::
I leave figuring out the exact command line as an exercise for the reader. I leave figuring out the exact command line as an exercise for the reader.
Finally, you can add downloaded news to the |app| library with:: Finally, you can add downloaded news to the calibre library with::
/opt/calibre/calibredb add --with-library /path/to/library outfile.epub /opt/calibre/calibredb add --with-library /path/to/library outfile.epub
Remember to read the command line documentation section of the |app| User Manual to learn more about these, and other commands. Remember to read the command line documentation section of the calibre User Manual to learn more about these, and other commands.
.. note:: Some parts of calibre require a X server. If you're lucky, nothing you do will fall into this category, if not, you will have to look into using xvfb. .. note:: Some parts of calibre require a X server. If you're lucky, nothing you do will fall into this category, if not, you will have to look into using xvfb.

4
manual/glossary.rst
View File

@ -5,10 +5,10 @@ Glossary
.. glossary:: .. glossary::
RSS RSS
**RSS** *(Really Simple Syndication)* is a web feed format that is used to publish frequently updated content, like news articles, blog posts, etc. It is a format that is particularly suited to being read by computers, and is therefore the preferred way of getting content from the web into an ebook. There are many other feed formats in use on the Internet, and |app| understands most of them. In particular, it has good support for the *ATOM* format, which is commonly used for blogs. **RSS** *(Really Simple Syndication)* is a web feed format that is used to publish frequently updated content, like news articles, blog posts, etc. It is a format that is particularly suited to being read by computers, and is therefore the preferred way of getting content from the web into an ebook. There are many other feed formats in use on the Internet, and calibre understands most of them. In particular, it has good support for the *ATOM* format, which is commonly used for blogs.
recipe recipe
A recipe is a set of instructions that teach |app| how to convert an online news source, such as a magazine or a blog, into an ebook. A recipe is essentially `Python <http://www.python.org>`_ code. As such, it is capable of converting arbitrarily complex news sources into ebooks. At the simplest level, it is just a set of variables, such as URLs, that give |app| enough information to go out onto the Internet and download the news. A recipe is a set of instructions that teach calibre how to convert an online news source, such as a magazine or a blog, into an ebook. A recipe is essentially `Python <http://www.python.org>`_ code. As such, it is capable of converting arbitrarily complex news sources into ebooks. At the simplest level, it is just a set of variables, such as URLs, that give calibre enough information to go out onto the Internet and download the news.
HTML HTML
**HTML** *(Hyper Text Mark-Up Language)*, a subset of Standard Generalized Mark-Up Language (SGML) for electronic publishing, is the specific standard used for the World Wide Web. **HTML** *(Hyper Text Mark-Up Language)*, a subset of Standard Generalized Mark-Up Language (SGML) for electronic publishing, is the specific standard used for the World Wide Web.

84
manual/gui.rst
View File

@ -5,13 +5,13 @@ The Graphical User Interface
The Graphical User Interface *(GUI)* provides access to all The Graphical User Interface *(GUI)* provides access to all
library management and ebook format conversion features. The basic workflow library management and ebook format conversion features. The basic workflow
for using |app| is to first add books to the library from your hard disk. for using calibre is to first add books to the library from your hard disk.
|app| will automatically try to read metadata from the books and add them calibre will automatically try to read metadata from the books and add them
to its internal database. Once they are in the database, you can perform various to its internal database. Once they are in the database, you can perform various
:ref:`actions` on them that include conversion from one format to another, :ref:`actions` on them that include conversion from one format to another,
transfer to the reading device, viewing on your computer, and editing metadata. transfer to the reading device, viewing on your computer, and editing metadata.
The latter includes modifying the cover, description, and tags among other details. The latter includes modifying the cover, description, and tags among other details.
Note that |app| creates copies of the files you add to it. Your original files are left untouched. Note that calibre creates copies of the files you add to it. Your original files are left untouched.
The interface is divided into various sections: The interface is divided into various sections:
@ -47,9 +47,9 @@ Add books
1. **Add books from a single directory**: Opens a file chooser dialog and allows you to specify which books in a directory should be added. This action is *context sensitive*, i.e. it depends on which :ref:`catalog <catalogs>` you have selected. If you have selected the :guilabel:`Library`, books will be added to the library. If you have selected the ebook reader device, the books will be uploaded to the device, and so on. 1. **Add books from a single directory**: Opens a file chooser dialog and allows you to specify which books in a directory should be added. This action is *context sensitive*, i.e. it depends on which :ref:`catalog <catalogs>` you have selected. If you have selected the :guilabel:`Library`, books will be added to the library. If you have selected the ebook reader device, the books will be uploaded to the device, and so on.
2. **Add books from directories, including sub-directories (One book per directory, assumes every ebook file is the same book in a different format)**: Allows you to choose a directory. The directory and all its sub-directories are scanned recursively, and any ebooks found are added to the library. |app| assumes that each directory contains a single book. All ebook files in a directory are assumed to be the same book in different formats. This action is the inverse of the :ref:`Save to disk <save_to_disk_multiple>` action, i.e. you can :guilabel:`Save to disk`, delete the books and re-add them with no lost information except for the date (this assumes you have not changed any of the setting for the Save to disk action). 2. **Add books from directories, including sub-directories (One book per directory, assumes every ebook file is the same book in a different format)**: Allows you to choose a directory. The directory and all its sub-directories are scanned recursively, and any ebooks found are added to the library. calibre assumes that each directory contains a single book. All ebook files in a directory are assumed to be the same book in different formats. This action is the inverse of the :ref:`Save to disk <save_to_disk_multiple>` action, i.e. you can :guilabel:`Save to disk`, delete the books and re-add them with no lost information except for the date (this assumes you have not changed any of the setting for the Save to disk action).
3. **Add books from directories, including sub-directories (Multiple books per directory, assumes every ebook file is a different book)**: Allows you to choose a directory. The directory and all its sub-directories are scanned recursively and any ebooks found are added to the library. |app| assumes that each directory contains many books. All ebook files with the same name in a directory are assumed to be the same book in different formats. Ebooks with different names are added as different books. 3. **Add books from directories, including sub-directories (Multiple books per directory, assumes every ebook file is a different book)**: Allows you to choose a directory. The directory and all its sub-directories are scanned recursively and any ebooks found are added to the library. calibre assumes that each directory contains many books. All ebook files with the same name in a directory are assumed to be the same book in different formats. Ebooks with different names are added as different books.
4. **Add multiple books from archive (ZIP/RAR)**: Allows you to add multiple ebooks that are stored inside a single ZIP or RAR file. It is a convenient shortcut that avoids having to first unzip the archive and then add the books via one of the above two options. 4. **Add multiple books from archive (ZIP/RAR)**: Allows you to add multiple ebooks that are stored inside a single ZIP or RAR file. It is a convenient shortcut that avoids having to first unzip the archive and then add the books via one of the above two options.
@ -95,8 +95,8 @@ Convert books
|cei| Ebooks can be converted from a number of formats into whatever format your ebook reader prefers. |cei| Ebooks can be converted from a number of formats into whatever format your ebook reader prefers.
Many ebooks available for purchase will be protected by `Digital Rights Management <http://drmfree.calibre-ebook.com/about#drm>`_ *(DRM)* technology. Many ebooks available for purchase will be protected by `Digital Rights Management <http://drmfree.calibre-ebook.com/about#drm>`_ *(DRM)* technology.
|app| will not convert these ebooks. It is easy to remove the DRM from many formats, but as this may be illegal, calibre will not convert these ebooks. It is easy to remove the DRM from many formats, but as this may be illegal,
you will have to find tools to liberate your books yourself and then use |app| to convert them. you will have to find tools to liberate your books yourself and then use calibre to convert them.
For most people, conversion should be a simple one-click affair. If you want to learn more about the conversion process, see :ref:`conversion`. For most people, conversion should be a simple one-click affair. If you want to learn more about the conversion process, see :ref:`conversion`.
@ -120,7 +120,7 @@ View
.. |vi| image:: images/view.png .. |vi| image:: images/view.png
:class: float-right-img :class: float-right-img
|vi| The :guilabel:`View` action displays the book in an ebook viewer program. |app| has a built-in viewer for many ebook formats. |vi| The :guilabel:`View` action displays the book in an ebook viewer program. calibre has a built-in viewer for many ebook formats.
For other formats it uses the default operating system application. You can configure which formats should open with the internal viewer via For other formats it uses the default operating system application. You can configure which formats should open with the internal viewer via
Preferences->Behavior. If a book has more than one format, you can view a particular format by doing a right-click on the button. Preferences->Behavior. If a book has more than one format, you can view a particular format by doing a right-click on the button.
@ -138,10 +138,10 @@ Send to device
2. **Send to card (A)**: The selected books are transferred to the storage card (A) on the ebook reader. 2. **Send to card (A)**: The selected books are transferred to the storage card (A) on the ebook reader.
3. **Send to card (B)**: The selected books are transferred to the storage card (B) on the ebook reader. 3. **Send to card (B)**: The selected books are transferred to the storage card (B) on the ebook reader.
4. **Send specific format to**: The selected books are transferred to the selected storage location on the device, in the format that you specify. 4. **Send specific format to**: The selected books are transferred to the selected storage location on the device, in the format that you specify.
5. **Eject device**: Detaches the device from |app|. 5. **Eject device**: Detaches the device from calibre.
6. **Set default send to device action**: Allows you to specify which of the options, 1 through 5 above or 7 below, will be the default action when you click the main button. 6. **Set default send to device action**: Allows you to specify which of the options, 1 through 5 above or 7 below, will be the default action when you click the main button.
7. **Send and delete from library**: The selected books are transferred to the selected storage location on the device and then **deleted** from the Library. 7. **Send and delete from library**: The selected books are transferred to the selected storage location on the device and then **deleted** from the Library.
8. **Fetch Annotations (experimental)**: Transfers annotations you may have made on an ebook on your device to the comments metadata of the book in the |app| library. 8. **Fetch Annotations (experimental)**: Transfers annotations you may have made on an ebook on your device to the comments metadata of the book in the calibre library.
You can control the file name and folder structure of files sent to the device by setting up a template in You can control the file name and folder structure of files sent to the device by setting up a template in
:guilabel:`Preferences->Import/Export->Sending books to devices`. Also see :ref:`templatelangcalibre`. :guilabel:`Preferences->Import/Export->Sending books to devices`. Also see :ref:`templatelangcalibre`.
@ -161,7 +161,7 @@ The :guilabel:`Fetch news` action has three variations, accessed by doing a righ
1. **Schedule news download**: Allows you to schedule the download of of your selected news sources from a list of hundreds available. Scheduling can be set individually for each news source you select and the scheduling is flexible allowing you to select specific days of the week or a frequency of days between downloads. 1. **Schedule news download**: Allows you to schedule the download of of your selected news sources from a list of hundreds available. Scheduling can be set individually for each news source you select and the scheduling is flexible allowing you to select specific days of the week or a frequency of days between downloads.
2. **Add a custom news source**: Allows you to create a simple recipe for downloading news from a custom news site that you wish to access. Creating the recipe can be as simple as specifying an RSS news feed URL, or you can be more prescriptive by creating Python-based code for the task. For more information see :ref:`news`. 2. **Add a custom news source**: Allows you to create a simple recipe for downloading news from a custom news site that you wish to access. Creating the recipe can be as simple as specifying an RSS news feed URL, or you can be more prescriptive by creating Python-based code for the task. For more information see :ref:`news`.
3. **Download all scheduled news sources**: Causes |app| to immediately begin downloading all news sources that you have scheduled. 3. **Download all scheduled news sources**: Causes calibre to immediately begin downloading all news sources that you have scheduled.
.. _library: .. _library:
@ -171,16 +171,16 @@ Library
.. |lii| image:: images/library.png .. |lii| image:: images/library.png
:class: float-right-img :class: float-right-img
|lii| The :guilabel:`Library` action allows you to create, switch between, rename or remove a Library. |app| allows you to create as many libraries as you wish. You could, for instance, create a fiction library, a non-fiction library, a foreign language library, a project library, or any structure that suits your needs. Libraries are the highest organizational structure within |app|. Each library has its own set of books, tags, categories and base storage location. |lii| The :guilabel:`Library` action allows you to create, switch between, rename or remove a Library. calibre allows you to create as many libraries as you wish. You could, for instance, create a fiction library, a non-fiction library, a foreign language library, a project library, or any structure that suits your needs. Libraries are the highest organizational structure within calibre. Each library has its own set of books, tags, categories and base storage location.
1. **Switch/create library...**: Allows you to; a) connect to a pre-existing |app| library at another location, b) create an empty library at a new location or, c) move the current library to a newly specified location. 1. **Switch/create library...**: Allows you to; a) connect to a pre-existing calibre library at another location, b) create an empty library at a new location or, c) move the current library to a newly specified location.
2. **Quick switch**: Allows you to switch between libraries that have been registered or created within |app|. 2. **Quick switch**: Allows you to switch between libraries that have been registered or created within calibre.
3. **Rename library**: Allows you to rename a Library. 3. **Rename library**: Allows you to rename a Library.
4. **Delete library**: Allows you to unregister a library from |app|. 4. **Delete library**: Allows you to unregister a library from calibre.
5. **<library name>**: Actions 5, 6 etc... give you immediate switch access between multiple libraries that you have created or attached to. This list contains only the 5 most frequently used libraries. For the complete list, use the Quick Switch menu. 5. **<library name>**: Actions 5, 6 etc... give you immediate switch access between multiple libraries that you have created or attached to. This list contains only the 5 most frequently used libraries. For the complete list, use the Quick Switch menu.
6. **Library maintenance**: Allows you to check the current library for data consistency issues and restore the current library's database from backups. 6. **Library maintenance**: Allows you to check the current library for data consistency issues and restore the current library's database from backups.
.. note:: Metadata about your ebooks, e.g. title, author, and tags, is stored in a single file in your |app| library folder called metadata.db. If this file gets corrupted (a very rare event), you can lose the metadata. Fortunately, |app| automatically backs up the metadata for every individual book in the book's folder as an OPF file. By using the Restore database action under Library Maintenance described above, you can have |app| rebuild the metadata.db file from the individual OPF files for you. .. note:: Metadata about your ebooks, e.g. title, author, and tags, is stored in a single file in your calibre library folder called metadata.db. If this file gets corrupted (a very rare event), you can lose the metadata. Fortunately, calibre automatically backs up the metadata for every individual book in the book's folder as an OPF file. By using the Restore database action under Library Maintenance described above, you can have calibre rebuild the metadata.db file from the individual OPF files for you.
You can copy or move books between different libraries (once you have more than one library setup) by right clicking on the book and selecting the action :guilabel:`Copy to library`. You can copy or move books between different libraries (once you have more than one library setup) by right clicking on the book and selecting the action :guilabel:`Copy to library`.
@ -191,8 +191,8 @@ Device
.. |dvi| image:: images/device.png .. |dvi| image:: images/device.png
:class: float-right-img :class: float-right-img
|dvi| The :guilabel:`Device` action allows you to view the books in the main memory or storage cards of your device, or to eject the device (detach it from |app|). |dvi| The :guilabel:`Device` action allows you to view the books in the main memory or storage cards of your device, or to eject the device (detach it from calibre).
This icon shows up automatically on the main |app| toolbar when you connect a supported device. You can click on it to see the books on your device. You can also drag and drop books from your |app| library onto the icon to transfer them to your device. Conversely, you can drag and drop books from your device onto the library icon on the toolbar to transfer books from your device to the |app| library. This icon shows up automatically on the main calibre toolbar when you connect a supported device. You can click on it to see the books on your device. You can also drag and drop books from your calibre library onto the icon to transfer them to your device. Conversely, you can drag and drop books from your device onto the library icon on the toolbar to transfer books from your device to the calibre library.
.. _save_to_disk: .. _save_to_disk:
@ -234,17 +234,17 @@ Connect/Share
.. |csi| image:: images/connect_share.png .. |csi| image:: images/connect_share.png
:class: float-right-img :class: float-right-img
|csi| The :guilabel:`Connect/Share` action allows you to manually connect to a device or folder on your computer. It also allows you to set up you |app| library for access via a web browser or email. |csi| The :guilabel:`Connect/Share` action allows you to manually connect to a device or folder on your computer. It also allows you to set up you calibre library for access via a web browser or email.
The :guilabel:`Connect/Share` action has four variations, accessed by doing a right-click on the button. The :guilabel:`Connect/Share` action has four variations, accessed by doing a right-click on the button.
1. **Connect to folder**: Allows you to connect to any folder on your computer as though it were a device and use all the facilities |app| has for devices with that folder. Useful if your device cannot be supported by |app| but is available as a USB disk. 1. **Connect to folder**: Allows you to connect to any folder on your computer as though it were a device and use all the facilities calibre has for devices with that folder. Useful if your device cannot be supported by calibre but is available as a USB disk.
2. **Connect to iTunes**: Allows you to connect to your iTunes books database as though it were a device. Once the books are sent to iTunes, you can use iTunes to make them available to your various iDevices. 2. **Connect to iTunes**: Allows you to connect to your iTunes books database as though it were a device. Once the books are sent to iTunes, you can use iTunes to make them available to your various iDevices.
3. **Start Content Server**: Starts |app|'s built-in web server. When started, your |app| library will be accessible via a web browser from the Internet (if you choose). You can configure how the web server is accessed by setting preferences at :guilabel:`Preferences->Sharing->Sharing over the net` 3. **Start Content Server**: Starts calibre's built-in web server. When started, your calibre library will be accessible via a web browser from the Internet (if you choose). You can configure how the web server is accessed by setting preferences at :guilabel:`Preferences->Sharing->Sharing over the net`
4. **Setup email based sharing of books**: Allows sharing of books and news feeds by email. After setting up email addresses for this option, |app| will send news updates and book updates to the entered email addresses. You can configure how |app| sends email by setting preferences at :guilabel:`Preferences->Sharing->Sharing books by email`. Once you have set up one or more email addresses, this menu entry will be replaced by menu entries to send books to the configured email addresses. 4. **Setup email based sharing of books**: Allows sharing of books and news feeds by email. After setting up email addresses for this option, calibre will send news updates and book updates to the entered email addresses. You can configure how calibre sends email by setting preferences at :guilabel:`Preferences->Sharing->Sharing books by email`. Once you have set up one or more email addresses, this menu entry will be replaced by menu entries to send books to the configured email addresses.
.. _remove_books: .. _remove_books:
@ -268,7 +268,7 @@ Remove books
6. **Remove matching books from device**: Allows you to remove ebook files from a connected device that match the books that are selected in the book list. 6. **Remove matching books from device**: Allows you to remove ebook files from a connected device that match the books that are selected in the book list.
.. note:: .. note::
Note that when you use Remove books to delete books from your |app| library, the book record is permanently deleted, but on Windows and OS X the files are placed into the recycle bin. This allows you to recover them if you change your mind. Note that when you use Remove books to delete books from your calibre library, the book record is permanently deleted, but on Windows and OS X the files are placed into the recycle bin. This allows you to recover them if you change your mind.
.. _configuration: .. _configuration:
@ -277,12 +277,12 @@ Preferences
.. |cbi| image:: images/preferences.png .. |cbi| image:: images/preferences.png
:class: float-right-img :class: float-right-img
|cbi| The :guilabel:`Preferences` action allows you to change the way various aspects of |app| work. It has four variations, accessed by doing a right-click on the button. |cbi| The :guilabel:`Preferences` action allows you to change the way various aspects of calibre work. It has four variations, accessed by doing a right-click on the button.
1. **Preferences**: Allows you to change the way various aspects of |app| work. Clicking the button also performs this action. 1. **Preferences**: Allows you to change the way various aspects of calibre work. Clicking the button also performs this action.
2. **Run welcome wizard**: Allows you to start the Welcome Wizard which appeared the first time you started |app|. 2. **Run welcome wizard**: Allows you to start the Welcome Wizard which appeared the first time you started calibre.
3. **Get plugins to enhance |app|**: Opens a new windows that shows plugins for |app|. These plugins are developed by third parties to extend |app|'s functionality. 3. **Get plugins to enhance calibre**: Opens a new windows that shows plugins for calibre. These plugins are developed by third parties to extend calibre's functionality.
4. **Restart in debug mode**: Allows you to enable a debugging mode that can assist the |app| developers in solving problems you encounter with the program. For most users this should remain disabled unless instructed by a developer to enable it. 4. **Restart in debug mode**: Allows you to enable a debugging mode that can assist the calibre developers in solving problems you encounter with the program. For most users this should remain disabled unless instructed by a developer to enable it.
.. _catalogs: .. _catalogs:
@ -291,13 +291,13 @@ Catalogs
.. image:: images/catalogs.png .. image:: images/catalogs.png
:align: center :align: center
A *catalog* is a collection of books. |app| can manage two types of different catalogs: A *catalog* is a collection of books. calibre can manage two types of different catalogs:
1. **Library**: This is a collection of books stored in your |app| library on your computer. 1. **Library**: This is a collection of books stored in your calibre library on your computer.
2. **Device**: This is a collection of books stored in your ebook reader. It will be available when you connect the reader to your computer. 2. **Device**: This is a collection of books stored in your ebook reader. It will be available when you connect the reader to your computer.
Many operations, such as adding books, deleting, viewing, etc., are context sensitive. So, for example, if you click the View button when you have the **Device** catalog selected, |app| will open the files on the device to view. If you have the **Library** catalog selected, files in your |app| library will be opened instead. Many operations, such as adding books, deleting, viewing, etc., are context sensitive. So, for example, if you click the View button when you have the **Device** catalog selected, calibre will open the files on the device to view. If you have the **Library** catalog selected, files in your calibre library will be opened instead.
.. _search_sort: .. _search_sort:
@ -437,7 +437,7 @@ Identifiers (e.g., isbn, doi, lccn etc) also use an extended syntax. First, note
Saving searches Saving searches
----------------- -----------------
|app| allows you to save a frequently used search under a special name and then reuse that search with a single click. To do this, create your search either by typing it in the search bar or using the Tag Browser. Then type the name you would like to give to the search in the Saved Searches box next to the search bar. Click the plus icon next to the saved searches box to save the search. calibre allows you to save a frequently used search under a special name and then reuse that search with a single click. To do this, create your search either by typing it in the search bar or using the Tag Browser. Then type the name you would like to give to the search in the Saved Searches box next to the search bar. Click the plus icon next to the saved searches box to save the search.
Now you can access your saved search in the Tag Browser under "Searches". A single click will allow you to reuse any arbitrarily complex search easily, without needing to re-create it. Now you can access your saved search in the Tag Browser under "Searches". A single click will allow you to reuse any arbitrarily complex search easily, without needing to re-create it.
@ -446,7 +446,7 @@ Now you can access your saved search in the Tag Browser under "Searches". A sing
Virtual Libraries Virtual Libraries
------------------- -------------------
A :guilabel:`Virtual Library` is a way to pretend that your |app| library has A :guilabel:`Virtual Library` is a way to pretend that your calibre library has
only a few books instead of its full collection. This is an excellent way to only a few books instead of its full collection. This is an excellent way to
partition your large collection of books into smaller, manageable chunks. To partition your large collection of books into smaller, manageable chunks. To
learn how to create and use virtual libraries, see the tutorial: learn how to create and use virtual libraries, see the tutorial:
@ -454,7 +454,7 @@ learn how to create and use virtual libraries, see the tutorial:
Guessing metadata from file names Guessing metadata from file names
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the :guilabel:`Add/Save` section of the configuration dialog, you can specify a regular expression that |app| will use to try and guess metadata from the names of ebook files In the :guilabel:`Add/Save` section of the configuration dialog, you can specify a regular expression that calibre will use to try and guess metadata from the names of ebook files
that you add to the library. The default regular expression is:: that you add to the library. The default regular expression is::
title - author title - author
@ -478,7 +478,7 @@ Book Details
The Book Details display shows the cover and all the metadata for the currently The Book Details display shows the cover and all the metadata for the currently
selected book. It can be hidden via the button in the lower right corner of the selected book. It can be hidden via the button in the lower right corner of the
main |app| window. The author names shown in the Book Detail panel are main calibre window. The author names shown in the Book Detail panel are
clickable, they will by default take you to the Wikipedia page for the author. clickable, they will by default take you to the Wikipedia page for the author.
This can be customized by right clicking on the author name and selecting This can be customized by right clicking on the author name and selecting
Manage this author. Manage this author.
@ -545,12 +545,12 @@ Cover Grid
.. image:: images/cover_grid.png .. image:: images/cover_grid.png
:align: center :align: center
You can have |app| display a grid of book covers instead of a list of books, if You can have calibre display a grid of book covers instead of a list of books, if
you prefer to browse your collection by covers instead. The :guilabel:`Cover you prefer to browse your collection by covers instead. The :guilabel:`Cover
Grid` is activated by clicking the grid button in the bottom right corner of Grid` is activated by clicking the grid button in the bottom right corner of
the main |app| window. You can customize the cover sizes and the background of the main calibre window. You can customize the cover sizes and the background of
the cover grid via :guilabel:`Preferences->Look & Feel->Cover Grid`. You can the cover grid via :guilabel:`Preferences->Look & Feel->Cover Grid`. You can
even have |app| display any specified field under the covers, such as title or even have calibre display any specified field under the covers, such as title or
authors or rating or a custom column of your own devising. authors or rating or a custom column of your own devising.
Cover Browser Cover Browser
@ -559,7 +559,7 @@ Cover Browser
.. image:: images/cover_browser.png .. image:: images/cover_browser.png
:align: center :align: center
In addition to the cover grid described above, you can also have |app| display In addition to the cover grid described above, you can also have calibre display
covers in the single row. This is activated via a button in the lower right covers in the single row. This is activated via a button in the lower right
corner of the main window. In :guilabel:`Preferences->Look & Feel->Cover corner of the main window. In :guilabel:`Preferences->Look & Feel->Cover
Browser` you can change the number of covers displayed, and even have the cover Browser` you can change the number of covers displayed, and even have the cover
@ -580,11 +580,11 @@ Some example Quickview usages: quickly seeing what other books:
without changing the contents of the library view. without changing the contents of the library view.
The Quickview window opens on top of the |app| window and will stay open until you explicitly close it. You can use Quickview and the |app| library view at the same time. For example, if in the |app| library view you click on a category column (tags, series, publisher, authors, etc) for a book, the Quickview window contents will change to show you in the left-hand side pane the items in that category for the selected book (e.g., the tags for that book). The first item in that list will be selected, and Quickview will show you on the right-hand side pane all the books in your library that reference that item. Click on an different item in the left-hand pane to see the books with that different item. The Quickview window opens on top of the calibre window and will stay open until you explicitly close it. You can use Quickview and the calibre library view at the same time. For example, if in the calibre library view you click on a category column (tags, series, publisher, authors, etc) for a book, the Quickview window contents will change to show you in the left-hand side pane the items in that category for the selected book (e.g., the tags for that book). The first item in that list will be selected, and Quickview will show you on the right-hand side pane all the books in your library that reference that item. Click on an different item in the left-hand pane to see the books with that different item.
Double-click on a book in the Quickview window to select that book in the library view. This will also change the items display in the QuickView window(the left-hand pane) to show the items in the newly-selected book. Double-click on a book in the Quickview window to select that book in the library view. This will also change the items display in the QuickView window(the left-hand pane) to show the items in the newly-selected book.
Shift- (or Ctrl-) double-click on a book in the Quickview window to open the edit metadata dialog on that book in the |app| window. Shift- (or Ctrl-) double-click on a book in the Quickview window to open the edit metadata dialog on that book in the calibre window.
You can see if a column can be Quickview'ed by hovering your mouse over the column heading and looking at the tooltip for that heading. You can also know by right-clicking on the column heading to see of the "Quickview" option is shown in the menu, in which case choosing that Quickview option is equivalent to pressing 'Q' in the current cell. You can see if a column can be Quickview'ed by hovering your mouse over the column heading and looking at the tooltip for that heading. You can also know by right-clicking on the column heading to see of the "Quickview" option is shown in the menu, in which case choosing that Quickview option is equivalent to pressing 'Q' in the current cell.
@ -610,7 +610,7 @@ The Jobs panel shows the number of currently running jobs. Jobs are tasks that r
Keyboard Shortcuts Keyboard Shortcuts
--------------------- ---------------------
Calibre has several keyboard shortcuts to save you time and mouse movement. These shortcuts are active in the book list view (when you're not editing the details of a particular book), and most of them affect the title you have selected. The |app| ebook viewer has its own shortcuts which can be customised by clicking the Preferences button in the viewer. Calibre has several keyboard shortcuts to save you time and mouse movement. These shortcuts are active in the book list view (when you're not editing the details of a particular book), and most of them affect the title you have selected. The calibre ebook viewer has its own shortcuts which can be customised by clicking the Preferences button in the viewer.
.. note:: .. note::

12
manual/index.rst
View File

@ -1,6 +1,6 @@
.. include:: simple_index.rst .. include:: simple_index.rst
The main |app| user interface The main calibre user interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. toctree:: .. toctree::
@ -8,7 +8,7 @@ The main |app| user interface
gui gui
Adding your favorite news website to |app| Adding your favorite news website to calibre
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. toctree:: .. toctree::
@ -16,7 +16,7 @@ Adding your favorite news website to |app|
news news
The |app| ebook viewer The calibre ebook viewer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. toctree:: .. toctree::
@ -24,7 +24,7 @@ The |app| ebook viewer
viewer viewer
Customizing |app|'s ebook conversion Customizing calibre's ebook conversion
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. toctree:: .. toctree::
@ -72,7 +72,7 @@ Tutorials
tutorials tutorials
Customizing |app| Customizing calibre
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. toctree:: .. toctree::
@ -88,7 +88,7 @@ The Command Line Interface
generated/|lang|/cli-index generated/|lang|/cli-index
Setting up a |app| development environment Setting up a calibre development environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. toctree:: .. toctree::

18
manual/metadata.rst
View File

@ -8,7 +8,7 @@ Editing Ebook Metadata
:local: :local:
Ebooks come in all shapes and sizes and more often than not, their metadata (things like title/author/series/publisher) is incomplete or incorrect. Ebooks come in all shapes and sizes and more often than not, their metadata (things like title/author/series/publisher) is incomplete or incorrect.
The simplest way to change metadata in |app| is to simply double click on an entry and type in the correct replacement. The simplest way to change metadata in calibre is to simply double click on an entry and type in the correct replacement.
For more sophisticated, "power editing" use the edit metadata tools discussed below. For more sophisticated, "power editing" use the edit metadata tools discussed below.
Editing the metadata of one book at a time Editing the metadata of one book at a time
@ -17,27 +17,27 @@ Editing the metadata of one book at a time
Click the book you want to edit and then click the :guilabel:`Edit metadata` button or press the ``E`` key. A dialog opens that allows you to edit all aspects of the metadata. It has various features to make editing faster and more efficient. A list of the commonly used tips: Click the book you want to edit and then click the :guilabel:`Edit metadata` button or press the ``E`` key. A dialog opens that allows you to edit all aspects of the metadata. It has various features to make editing faster and more efficient. A list of the commonly used tips:
* You can click the button in between title and authors to swap them automatically. * You can click the button in between title and authors to swap them automatically.
* You can click the button next to author sort to have |app| automatically fill it in using the sort values stored with each author. Use the :guilabel:`Manage authors` dialog to see and change the authors' sort values. This dialog can be opened by clicking and holding the button next to author sort. * You can click the button next to author sort to have calibre automatically fill it in using the sort values stored with each author. Use the :guilabel:`Manage authors` dialog to see and change the authors' sort values. This dialog can be opened by clicking and holding the button next to author sort.
* You can click the button next to tags to use the Tag Editor to manage the tags associated with the book. * You can click the button next to tags to use the Tag Editor to manage the tags associated with the book.
* The ISBN box will have a red background if you enter an invalid ISBN. It will be green for valid ISBNs * The ISBN box will have a red background if you enter an invalid ISBN. It will be green for valid ISBNs
* The author sort box will be red if the author sort value differs from what |app| thinks it should be. * The author sort box will be red if the author sort value differs from what calibre thinks it should be.
Downloading metadata Downloading metadata
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
The nicest feature of the edit metadata dialog is its ability to automatically fill in many metadata fields by getting metadata from various websites. Currently, |app| uses isbndb.com, Google Books, Amazon and Library Thing. The metadata download can fill in Title, author, series, tags, rating, description and ISBN for you. The nicest feature of the edit metadata dialog is its ability to automatically fill in many metadata fields by getting metadata from various websites. Currently, calibre uses isbndb.com, Google Books, Amazon and Library Thing. The metadata download can fill in Title, author, series, tags, rating, description and ISBN for you.
To use the download, fill in the title and author fields and click the :guilabel:`Fetch metadata` button. |app| will present you with a list of books that most closely match the title and author. If you fill in the ISBN field first, it will be used in preference to the title and author. If no matches are found, try making your search a little less specific by including only some key words in the title and only the author last name. To use the download, fill in the title and author fields and click the :guilabel:`Fetch metadata` button. calibre will present you with a list of books that most closely match the title and author. If you fill in the ISBN field first, it will be used in preference to the title and author. If no matches are found, try making your search a little less specific by including only some key words in the title and only the author last name.
Managing book formats Managing book formats
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
In |app|, a single book entry can have many different *formats* associated with it. For example you may have obtained the Complete Works of Shakespeare in EPUB format and later converted it to MOBI to read on your Kindle. |app| automatically manages multiple formats for you. In the :guilabel:`Available formats` section of the Edit metadata dialog, you can manage these formats. You can add a new format, delete an existing format and also ask |app| to set the metadata and cover for the book entry from the metadata in one of the formats. In calibre, a single book entry can have many different *formats* associated with it. For example you may have obtained the Complete Works of Shakespeare in EPUB format and later converted it to MOBI to read on your Kindle. calibre automatically manages multiple formats for you. In the :guilabel:`Available formats` section of the Edit metadata dialog, you can manage these formats. You can add a new format, delete an existing format and also ask calibre to set the metadata and cover for the book entry from the metadata in one of the formats.
All about covers All about covers
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
You can ask |app| to download book covers for you, provided the book has a known ISBN. Alternatively you can specify a file on your computer to use as the cover. |app| can even generate a default cover with basic metadata on it for you. You can drag and drop images onto the cover to change it and also right click to copy/paste cover images. You can ask calibre to download book covers for you, provided the book has a known ISBN. Alternatively you can specify a file on your computer to use as the cover. calibre can even generate a default cover with basic metadata on it for you. You can drag and drop images onto the cover to change it and also right click to copy/paste cover images.
In addition, there is a button to automatically trim borders from the cover, in case your cover image has an ugly border. In addition, there is a button to automatically trim borders from the cover, in case your cover image has an ugly border.
@ -60,7 +60,7 @@ If the field you are searching on is a `multiple` field like tags, then each tag
If you want the search to ignore upper/lowercase differences, uncheck the `Case sensitive` box. If you want the search to ignore upper/lowercase differences, uncheck the `Case sensitive` box.
You can have |app| change the case of the result (information after the replace has happened) by choosing one of the functions from the `Apply function after replace` box. The operations available are: You can have calibre change the case of the result (information after the replace has happened) by choosing one of the functions from the `Apply function after replace` box. The operations available are:
* `Lower case` -- change all the characters in the field to lower case * `Lower case` -- change all the characters in the field to lower case
* `Upper case` -- change all the characters in the field to upper case * `Upper case` -- change all the characters in the field to upper case
@ -74,7 +74,7 @@ The third and most important is that the replace string can make reference to pa
One useful pattern: assume you want to change the case of an entire field. The easiest way to do this is to use character mode, but lets further assume you want to use regular expression mode. The search expression should be `(.*)` the replace expression should be `\\1`, and the desired case change function should be selected. One useful pattern: assume you want to change the case of an entire field. The easiest way to do this is to use character mode, but lets further assume you want to use regular expression mode. The search expression should be `(.*)` the replace expression should be `\\1`, and the desired case change function should be selected.
Finally, in regular expression mode you can copy values from one field to another. Simply make the source and destination field different. The copy can replace the destination field, prepend to the field (add to the front), or append to the field (add at the end). The 'use comma' checkbox tells |app| to (or not to) add a comma between the text and the destination field in prepend and append modes. If the destination is multiple (e.g., tags), then you cannot uncheck this box. Finally, in regular expression mode you can copy values from one field to another. Simply make the source and destination field different. The copy can replace the destination field, prepend to the field (add to the front), or append to the field (add at the end). The 'use comma' checkbox tells calibre to (or not to) add a comma between the text and the destination field in prepend and append modes. If the destination is multiple (e.g., tags), then you cannot uncheck this box.
Search and replace is done after all the other metadata changes in the other tabs are applied. This can lead to some confusion, because the test boxes will show the information before the other changes, but the operation will be applied after the other changes. If you have any doubts about what is going to happen, do not mix search/replace with other changes. Search and replace is done after all the other metadata changes in the other tabs are applied. This can lead to some confusion, because the test boxes will show the information before the other changes, but the operation will be applied after the other changes. If you have any doubts about what is going to happen, do not mix search/replace with other changes.

24
manual/news.rst
View File

@ -3,7 +3,7 @@
Adding your favorite news website Adding your favorite news website
================================== ==================================
|app| has a powerful, flexible and easy-to-use framework for downloading news from the Internet and converting it into an ebook. The following will show you, by means of examples, how to get news from various websites. calibre has a powerful, flexible and easy-to-use framework for downloading news from the Internet and converting it into an ebook. The following will show you, by means of examples, how to get news from various websites.
To gain an understanding of how to use the framework, follow the examples in the order listed below: To gain an understanding of how to use the framework, follow the examples in the order listed below:
@ -14,7 +14,7 @@ To gain an understanding of how to use the framework, follow the examples in the
Completely automatic fetching Completely automatic fetching
------------------------------- -------------------------------
If your news source is simple enough, |app| may well be able to fetch it completely automatically, all you need to do is provide the URL. |app| gathers all the information needed to download a news source into a :term:`recipe`. In order to tell |app| about a news source, you have to create a :term:`recipe` for it. Let's see some examples: If your news source is simple enough, calibre may well be able to fetch it completely automatically, all you need to do is provide the URL. calibre gathers all the information needed to download a news source into a :term:`recipe`. In order to tell calibre about a news source, you have to create a :term:`recipe` for it. Let's see some examples:
.. _portfolio: .. _portfolio:
@ -28,7 +28,7 @@ Lets pick a couple of feeds that look interesting:
#. Business Travel: http://feeds.portfolio.com/portfolio/businesstravel #. Business Travel: http://feeds.portfolio.com/portfolio/businesstravel
#. Tech Observer: http://feeds.portfolio.com/portfolio/thetechobserver #. Tech Observer: http://feeds.portfolio.com/portfolio/thetechobserver
I got the URLs by clicking the little orange RSS icon next to each feed name. To make |app| download the feeds and convert them into an ebook, you should right click the :guilabel:`Fetch news` button and then the :guilabel:`Add a custom news source` menu item. A dialog similar to that shown below should open up. I got the URLs by clicking the little orange RSS icon next to each feed name. To make calibre download the feeds and convert them into an ebook, you should right click the :guilabel:`Fetch news` button and then the :guilabel:`Add a custom news source` menu item. A dialog similar to that shown below should open up.
.. image:: images/custom_news.png .. image:: images/custom_news.png
:align: center :align: center
@ -53,7 +53,7 @@ Lets try the following two feeds from *The BBC*:
#. News Front Page: http://newsrss.bbc.co.uk/rss/newsonline_world_edition/front_page/rss.xml #. News Front Page: http://newsrss.bbc.co.uk/rss/newsonline_world_edition/front_page/rss.xml
#. Science/Nature: http://newsrss.bbc.co.uk/rss/newsonline_world_edition/science/nature/rss.xml #. Science/Nature: http://newsrss.bbc.co.uk/rss/newsonline_world_edition/science/nature/rss.xml
Follow the procedure outlined in :ref:`portfolio` to create a recipe for *The BBC* (using the feeds above). Looking at the downloaded ebook, we see that |app| has done a creditable job of extracting only the content you care about from each article's webpage. However, the extraction process is not perfect. Sometimes it leaves in undesirable content like menus and navigation aids or it removes content that should have been left alone, like article headings. In order, to have perfect content extraction, we will need to customize the fetch process, as described in the next section. Follow the procedure outlined in :ref:`portfolio` to create a recipe for *The BBC* (using the feeds above). Looking at the downloaded ebook, we see that calibre has done a creditable job of extracting only the content you care about from each article's webpage. However, the extraction process is not perfect. Sometimes it leaves in undesirable content like menus and navigation aids or it removes content that should have been left alone, like article headings. In order, to have perfect content extraction, we will need to customize the fetch process, as described in the next section.
Customizing the fetch process Customizing the fetch process
-------------------------------- --------------------------------
@ -94,7 +94,7 @@ This is python, so indentation is important. After you've added the lines, it sh
.. image:: images/bbc_altered.png .. image:: images/bbc_altered.png
:align: center :align: center
In the above, ``def print_version(self, url)`` defines a *method* that is called by |app| for every article. ``url`` is the URL of the original article. What ``print_version`` does is take that url and replace it with the new URL that points to the print version of the article. To learn about `python <http://www.python.org>`_ see the `tutorial <http://docs.python.org/tut/>`_. In the above, ``def print_version(self, url)`` defines a *method* that is called by calibre for every article. ``url`` is the URL of the original article. What ``print_version`` does is take that url and replace it with the new URL that points to the print version of the article. To learn about `python <http://www.python.org>`_ see the `tutorial <http://docs.python.org/tut/>`_.
Now, click the :guilabel:`Add/update recipe` button and your changes will be saved. Re-download the ebook. You should have a much improved ebook. One of the problems with the new version is that the fonts on the print version webpage are too small. This is automatically fixed when converting to an ebook, but even after the fixing process, the font size of the menus and navigation bar to become too large relative to the article text. To fix this, we will do some more customization, in the next section. Now, click the :guilabel:`Add/update recipe` button and your changes will be saved. Re-download the ebook. You should have a much improved ebook. One of the problems with the new version is that the fonts on the print version webpage are too small. This is automatically fixed when converting to an ebook, but even after the fixing process, the font size of the menus and navigation bar to become too large relative to the article text. To fix this, we will do some more customization, in the next section.
@ -117,7 +117,7 @@ The new version looks pretty good. If you're a perfectionist, you'll want to rea
Slicing and dicing Slicing and dicing
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
|app| contains very powerful and flexible abilities when it comes to manipulating downloaded content. To show off a couple of these, let's look at our old friend the :ref:`The BBC <bbc1>` recipe again. Looking at the source code (:term:`HTML`) of a couple of articles (print version), we see that they have a footer that contains no useful information, contained in calibre contains very powerful and flexible abilities when it comes to manipulating downloaded content. To show off a couple of these, let's look at our old friend the :ref:`The BBC <bbc1>` recipe again. Looking at the source code (:term:`HTML`) of a couple of articles (print version), we see that they have a footer that contains no useful information, contained in
.. code-block:: html .. code-block:: html
@ -133,11 +133,11 @@ to the recipe. Finally, lets replace some of the :term:`CSS` that we disabled ea
extra_css = '.headline {font-size: x-large;} \n .fact { padding-top: 10pt }' extra_css = '.headline {font-size: x-large;} \n .fact { padding-top: 10pt }'
With these additions, our recipe has become "production quality", indeed it is very close to the actual recipe used by |app| for the *BBC*, shown below: With these additions, our recipe has become "production quality", indeed it is very close to the actual recipe used by calibre for the *BBC*, shown below:
.. literalinclude:: ../../../recipes/bbc.recipe .. literalinclude:: ../../../recipes/bbc.recipe
This :term:`recipe` explores only the tip of the iceberg when it comes to the power of |app|. To explore more of the abilities of |app| we'll examine a more complex real life example in the next section. This :term:`recipe` explores only the tip of the iceberg when it comes to the power of calibre. To explore more of the abilities of calibre we'll examine a more complex real life example in the next section.
Real life example Real life example
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
@ -250,7 +250,7 @@ The next interesting feature is::
def get_browser(self): def get_browser(self):
... ...
``needs_subscription = True`` tells |app| that this recipe needs a username and password in order to access the content. This causes, |app| to ask for a username and password whenever you try to use this recipe. The code in :meth:`calibre.web.feeds.news.BasicNewsRecipe.get_browser` actually does the login into the NYT website. Once logged in, |app| will use the same, logged in, browser instance to fetch all content. See `mechanize <http://wwwsearch.sourceforge.net/mechanize/>`_ to understand the code in ``get_browser``. ``needs_subscription = True`` tells calibre that this recipe needs a username and password in order to access the content. This causes, calibre to ask for a username and password whenever you try to use this recipe. The code in :meth:`calibre.web.feeds.news.BasicNewsRecipe.get_browser` actually does the login into the NYT website. Once logged in, calibre will use the same, logged in, browser instance to fetch all content. See `mechanize <http://wwwsearch.sourceforge.net/mechanize/>`_ to understand the code in ``get_browser``.
The next new feature is the The next new feature is the
:meth:`calibre.web.feeds.news.BasicNewsRecipe.parse_index` method. Its job is :meth:`calibre.web.feeds.news.BasicNewsRecipe.parse_index` method. Its job is
@ -294,7 +294,7 @@ Once the download is complete, you can look at the downloaded :term:`HTML` by op
If you're satisfied with your recipe, and you feel there is enough demand to justify its inclusion into the set of built-in recipes, post your recipe in the `calibre recipes forum <http://www.mobileread.com/forums/forumdisplay.php?f=228>`_ to share it with other calibre users. If you're satisfied with your recipe, and you feel there is enough demand to justify its inclusion into the set of built-in recipes, post your recipe in the `calibre recipes forum <http://www.mobileread.com/forums/forumdisplay.php?f=228>`_ to share it with other calibre users.
.. note:: .. note::
On OS X, the command line tools are inside the |app| bundle, for example, On OS X, the command line tools are inside the calibre bundle, for example,
if you installed calibre in :file:`/Applications` the command line tools if you installed calibre in :file:`/Applications` the command line tools
are in :file:`/Applications/calibre.app/Contents/console.app/Contents/MacOS/`. are in :file:`/Applications/calibre.app/Contents/console.app/Contents/MacOS/`.
@ -316,10 +316,10 @@ To learn more about writing advanced recipes using some of the facilities, avail
The source code of ``BasicNewsRecipe`` The source code of ``BasicNewsRecipe``
`Built-in recipes <http://bazaar.launchpad.net/~kovid/calibre/trunk/files/head:/recipes/>`_ `Built-in recipes <http://bazaar.launchpad.net/~kovid/calibre/trunk/files/head:/recipes/>`_
The source code for the built-in recipes that come with |app| The source code for the built-in recipes that come with calibre
`The calibre recipes forum <http://www.mobileread.com/forums/forumdisplay.php?f=228>`_ `The calibre recipes forum <http://www.mobileread.com/forums/forumdisplay.php?f=228>`_
Lots of knowledgeable |app| recipe writers hang out here. Lots of knowledgeable calibre recipe writers hang out here.
API documentation API documentation

22
manual/regexp.rst
View File

@ -1,9 +1,9 @@
.. _regexptutorial: .. _regexptutorial:
All about using regular expressions in |app| All about using regular expressions in calibre
======================================================= =======================================================
Regular expressions are features used in many places in |app| to perform sophisticated manipulation of ebook content and metadata. This tutorial is a gentle introduction to getting you started with using regular expressions in |app|. Regular expressions are features used in many places in calibre to perform sophisticated manipulation of ebook content and metadata. This tutorial is a gentle introduction to getting you started with using regular expressions in calibre.
.. contents:: Contents .. contents:: Contents
:depth: 2 :depth: 2
@ -15,17 +15,17 @@ First, a word of warning and a word of courage
This is, inevitably, going to be somewhat technical- after all, regular expressions are a technical tool for doing technical stuff. I'm going to have to use some jargon and concepts that may seem complicated or convoluted. I'm going to try to explain those concepts as clearly as I can, but really can't do without using them at all. That being said, don't be discouraged by any jargon, as I've tried to explain everything new. And while regular expressions themselves may seem like an arcane, black magic (or, to be more prosaic, a random string of mumbo-jumbo letters and signs), I promise that they are not all that complicated. Even those who understand regular expressions really well have trouble reading the more complex ones, but writing them isn't as difficult- you construct the expression step by step. So, take a step and follow me into the rabbit hole. This is, inevitably, going to be somewhat technical- after all, regular expressions are a technical tool for doing technical stuff. I'm going to have to use some jargon and concepts that may seem complicated or convoluted. I'm going to try to explain those concepts as clearly as I can, but really can't do without using them at all. That being said, don't be discouraged by any jargon, as I've tried to explain everything new. And while regular expressions themselves may seem like an arcane, black magic (or, to be more prosaic, a random string of mumbo-jumbo letters and signs), I promise that they are not all that complicated. Even those who understand regular expressions really well have trouble reading the more complex ones, but writing them isn't as difficult- you construct the expression step by step. So, take a step and follow me into the rabbit hole.
Where in |app| can you use regular expressions? Where in calibre can you use regular expressions?
--------------------------------------------------- ---------------------------------------------------
There are a few places |app| uses regular expressions. There's the Search & Replace in conversion options, metadata detection from filenames in the import settings and Search & Replace when editing the metadata of books in bulk. There are a few places calibre uses regular expressions. There's the Search & Replace in conversion options, metadata detection from filenames in the import settings and Search & Replace when editing the metadata of books in bulk.
What on earth *is* a regular expression? What on earth *is* a regular expression?
------------------------------------------------ ------------------------------------------------
A regular expression is a way to describe sets of strings. A single regular expression can *match* a number of different strings. This is what makes regular expression so powerful -- they are a concise way of describing a potentially large number of variations. A regular expression is a way to describe sets of strings. A single regular expression can *match* a number of different strings. This is what makes regular expression so powerful -- they are a concise way of describing a potentially large number of variations.
.. note:: I'm using string here in the sense it is used in programming languages: a string of one or more characters, characters including actual characters, numbers, punctuation and so-called whitespace (linebreaks, tabulators etc.). Please note that generally, uppercase and lowercase characters are not considered the same, thus "a" being a different character from "A" and so forth. In |app|, regular expressions are case insensitive in the search bar, but not in the conversion options. There's a way to make every regular expression case insensitive, but we'll discuss that later. It gets complicated because regular expressions allow for variations in the strings it matches, so one expression can match multiple strings, which is why people bother using them at all. More on that in a bit. .. note:: I'm using string here in the sense it is used in programming languages: a string of one or more characters, characters including actual characters, numbers, punctuation and so-called whitespace (linebreaks, tabulators etc.). Please note that generally, uppercase and lowercase characters are not considered the same, thus "a" being a different character from "A" and so forth. In calibre, regular expressions are case insensitive in the search bar, but not in the conversion options. There's a way to make every regular expression case insensitive, but we'll discuss that later. It gets complicated because regular expressions allow for variations in the strings it matches, so one expression can match multiple strings, which is why people bother using them at all. More on that in a bit.
Care to explain? Care to explain?
-------------------- --------------------
@ -81,17 +81,17 @@ You missed...
In the beginning, you said there was a way to make a regular expression case insensitive? In the beginning, you said there was a way to make a regular expression case insensitive?
------------------------------------------------------------------------------------------------------------------ ------------------------------------------------------------------------------------------------------------------
Yes, I did, thanks for paying attention and reminding me. You can tell |app| how you want certain things handled by using something called flags. You include flags in your expression by using the special construct ``(?flags go here)`` where, obviously, you'd replace "flags go here" with the specific flags you want. For ignoring case, the flag is ``i``, thus you include ``(?i)`` in your expression. Thus, ``test(?i)`` would match "Test", "tEst", "TEst" and any case variation you could think of. Yes, I did, thanks for paying attention and reminding me. You can tell calibre how you want certain things handled by using something called flags. You include flags in your expression by using the special construct ``(?flags go here)`` where, obviously, you'd replace "flags go here" with the specific flags you want. For ignoring case, the flag is ``i``, thus you include ``(?i)`` in your expression. Thus, ``test(?i)`` would match "Test", "tEst", "TEst" and any case variation you could think of.
Another useful flag lets the dot match any character at all, *including* the newline, the flag ``s``. If you want to use multiple flags in an expression, just put them in the same statement: ``(?is)`` would ignore case and make the dot match all. It doesn't matter which flag you state first, ``(?si)`` would be equivalent to the above. By the way, good places for putting flags in your expression would be either the very beginning or the very end. That way, they don't get mixed up with anything else. Another useful flag lets the dot match any character at all, *including* the newline, the flag ``s``. If you want to use multiple flags in an expression, just put them in the same statement: ``(?is)`` would ignore case and make the dot match all. It doesn't matter which flag you state first, ``(?si)`` would be equivalent to the above. By the way, good places for putting flags in your expression would be either the very beginning or the very end. That way, they don't get mixed up with anything else.
I think I'm beginning to understand these regular expressions now... how do I use them in |app|? I think I'm beginning to understand these regular expressions now... how do I use them in calibre?
----------------------------------------------------------------------------------------------------- -----------------------------------------------------------------------------------------------------
Conversions Conversions
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Let's begin with the conversion settings, which is really neat. In the Search and Replace part, you can input a regexp (short for regular expression) that describes the string that will be replaced during the conversion. The neat part is the wizard. Click on the wizard staff and you get a preview of what |app| "sees" during the conversion process. Scroll down to the string you want to remove, select and copy it, paste it into the regexp field on top of the window. If there are variable parts, like page numbers or so, use sets and quantifiers to cover those, and while you're at it, remember to escape special characters, if there are some. Hit the button labeled :guilabel:`Test` and |app| highlights the parts it would replace were you to use the regexp. Once you're satisfied, hit OK and convert. Be careful if your conversion source has tags like this example:: Let's begin with the conversion settings, which is really neat. In the Search and Replace part, you can input a regexp (short for regular expression) that describes the string that will be replaced during the conversion. The neat part is the wizard. Click on the wizard staff and you get a preview of what calibre "sees" during the conversion process. Scroll down to the string you want to remove, select and copy it, paste it into the regexp field on top of the window. If there are variable parts, like page numbers or so, use sets and quantifiers to cover those, and while you're at it, remember to escape special characters, if there are some. Hit the button labeled :guilabel:`Test` and calibre highlights the parts it would replace were you to use the regexp. Once you're satisfied, hit OK and convert. Be careful if your conversion source has tags like this example::
Maybe, but the cops feel like you do, Anita. What's one more dead vampire? Maybe, but the cops feel like you do, Anita. What's one more dead vampire?
New laws don't change that. </p> New laws don't change that. </p>
@ -101,13 +101,13 @@ Let's begin with the conversion settings, which is really neat. In the Search an
<p class="calibre4"> It had only been two years since Addison v. Clark. <p class="calibre4"> It had only been two years since Addison v. Clark.
The court case gave us a revised version of what life was The court case gave us a revised version of what life was
(shamelessly ripped out of `this thread <http://www.mobileread.com/forums/showthread.php?t=75594">`_). You'd have to remove some of the tags as well. In this example, I'd recommend beginning with the tag ``<b class="calibre2">``, now you have to end with the corresponding closing tag (opening tags are ``<tag>``, closing tags are ``</tag>``), which is simply the next ``</b>`` in this case. (Refer to a good HTML manual or ask in the forum if you are unclear on this point.) The opening tag can be described using ``<b.*?>``, the closing tag using ``</b>``, thus we could remove everything between those tags using ``<b.*?>.*?</b>``. But using this expression would be a bad idea, because it removes everything enclosed by <b>- tags (which, by the way, render the enclosed text in bold print), and it's a fair bet that we'll remove portions of the book in this way. Instead, include the beginning of the enclosed string as well, making the regular expression ``<b.*?>\s*Generated\s+by\s+ABC\s+Amber\s+LIT.*?</b>`` The ``\s`` with quantifiers are included here instead of explicitly using the spaces as seen in the string to catch any variations of the string that might occur. Remember to check what |app| will remove to make sure you don't remove any portions you want to keep if you test a new expression. If you only check one occurrence, you might miss a mismatch somewhere else in the text. Also note that should you accidentally remove more or fewer tags than you actually wanted to, |app| tries to repair the damaged code after doing the removal. (shamelessly ripped out of `this thread <http://www.mobileread.com/forums/showthread.php?t=75594">`_). You'd have to remove some of the tags as well. In this example, I'd recommend beginning with the tag ``<b class="calibre2">``, now you have to end with the corresponding closing tag (opening tags are ``<tag>``, closing tags are ``</tag>``), which is simply the next ``</b>`` in this case. (Refer to a good HTML manual or ask in the forum if you are unclear on this point.) The opening tag can be described using ``<b.*?>``, the closing tag using ``</b>``, thus we could remove everything between those tags using ``<b.*?>.*?</b>``. But using this expression would be a bad idea, because it removes everything enclosed by <b>- tags (which, by the way, render the enclosed text in bold print), and it's a fair bet that we'll remove portions of the book in this way. Instead, include the beginning of the enclosed string as well, making the regular expression ``<b.*?>\s*Generated\s+by\s+ABC\s+Amber\s+LIT.*?</b>`` The ``\s`` with quantifiers are included here instead of explicitly using the spaces as seen in the string to catch any variations of the string that might occur. Remember to check what calibre will remove to make sure you don't remove any portions you want to keep if you test a new expression. If you only check one occurrence, you might miss a mismatch somewhere else in the text. Also note that should you accidentally remove more or fewer tags than you actually wanted to, calibre tries to repair the damaged code after doing the removal.
Adding books Adding books
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
Another thing you can use regular expressions for is to extract metadata from filenames. You can find this feature in the "Adding books" part of the settings. There's a special feature here: You can use field names for metadata fields, for example ``(?P<title>)`` would indicate that calibre uses this part of the string as book title. The allowed field names are listed in the windows, together with another nice test field. An example: Say you want to import a whole bunch of files named like ``Classical Texts: The Divine Comedy by Dante Alighieri.mobi``. Another thing you can use regular expressions for is to extract metadata from filenames. You can find this feature in the "Adding books" part of the settings. There's a special feature here: You can use field names for metadata fields, for example ``(?P<title>)`` would indicate that calibre uses this part of the string as book title. The allowed field names are listed in the windows, together with another nice test field. An example: Say you want to import a whole bunch of files named like ``Classical Texts: The Divine Comedy by Dante Alighieri.mobi``.
(Obviously, this is already in your library, since we all love classical italian poetry) or ``Science Fiction epics: The Foundation Trilogy by Isaac Asimov.epub``. This is obviously a naming scheme that |app| won't extract any meaningful data out of - its standard expression for extracting metadata is ``(?P<title>.+) - (?P<author>[^_]+)``. A regular expression that works here would be ``[a-zA-Z]+: (?P<title>.+) by (?P<author>.+)``. Please note that, inside the group for the metadata field, you need to use expressions to describe what the field actually matches. And also note that, when using the test field |app| provides, you need to add the file extension to your testing filename, otherwise you won't get any matches at all, despite using a working expression. (Obviously, this is already in your library, since we all love classical italian poetry) or ``Science Fiction epics: The Foundation Trilogy by Isaac Asimov.epub``. This is obviously a naming scheme that calibre won't extract any meaningful data out of - its standard expression for extracting metadata is ``(?P<title>.+) - (?P<author>[^_]+)``. A regular expression that works here would be ``[a-zA-Z]+: (?P<title>.+) by (?P<author>.+)``. Please note that, inside the group for the metadata field, you need to use expressions to describe what the field actually matches. And also note that, when using the test field calibre provides, you need to add the file extension to your testing filename, otherwise you won't get any matches at all, despite using a working expression.
Bulk editing metadata Bulk editing metadata
^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
@ -116,7 +116,7 @@ The last part is regular expression search and replace in metadata fields. You c
Well, that just about concludes the very short introduction to regular expressions. Hopefully I'll have shown you enough to at least get you started and to enable you to continue learning by yourself- a good starting point would be the `Python documentation for regexps <http://docs.python.org/library/re.html>`_. Well, that just about concludes the very short introduction to regular expressions. Hopefully I'll have shown you enough to at least get you started and to enable you to continue learning by yourself- a good starting point would be the `Python documentation for regexps <http://docs.python.org/library/re.html>`_.
One last word of warning, though: Regexps are powerful, but also really easy to get wrong. |app| provides really great testing possibilities to see if your expressions behave as you expect them to. Use them. Try not to shoot yourself in the foot. (God, I love that expression...) But should you, despite the warning, injure your foot (or any other body parts), try to learn from it. One last word of warning, though: Regexps are powerful, but also really easy to get wrong. calibre provides really great testing possibilities to see if your expressions behave as you expect them to. Use them. Try not to shoot yourself in the foot. (God, I love that expression...) But should you, despite the warning, injure your foot (or any other body parts), try to learn from it.
Credits Credits
------------- -------------

10
manual/server.rst
View File

@ -1,9 +1,9 @@
.. _servertutorial: .. _servertutorial:
Integrating the |app| content server into other servers Integrating the calibre content server into other servers
========================================================== ==========================================================
Here, we will show you how to integrate the |app| content server into another server. The most common reason for this is to make use of SSL or more sophisticated authentication. There are two main techniques: Running the |app| content server as a standalone process and using a reverse proxy to connect it with your main server or running the content server in process in your main server with WSGI. The examples below are all for Apache 2.x on linux, but should be easily adaptable to other platforms. Here, we will show you how to integrate the calibre content server into another server. The most common reason for this is to make use of SSL or more sophisticated authentication. There are two main techniques: Running the calibre content server as a standalone process and using a reverse proxy to connect it with your main server or running the content server in process in your main server with WSGI. The examples below are all for Apache 2.x on linux, but should be easily adaptable to other platforms.
.. contents:: Contents .. contents:: Contents
:depth: 2 :depth: 2
@ -16,7 +16,7 @@ Using a reverse proxy
A reverse proxy is when your normal server accepts incoming requests and passes them onto the calibre server. It then reads the response from the calibre server and forwards it to the client. This means that you can simply run the calibre server as normal without trying to integrate it closely with your main server, and you can take advantage of whatever authentication systems you main server has in place. This is the simplest approach as it allows you to use the binary calibre install with no external dependencies/system integration requirements. Below, is an example of how to achieve this with Apache as your main server, but it will work with any server that supports Reverse Proxies. A reverse proxy is when your normal server accepts incoming requests and passes them onto the calibre server. It then reads the response from the calibre server and forwards it to the client. This means that you can simply run the calibre server as normal without trying to integrate it closely with your main server, and you can take advantage of whatever authentication systems you main server has in place. This is the simplest approach as it allows you to use the binary calibre install with no external dependencies/system integration requirements. Below, is an example of how to achieve this with Apache as your main server, but it will work with any server that supports Reverse Proxies.
First start the |app| content server as shown below:: First start the calibre content server as shown below::
calibre-server --url-prefix /calibre --port 8080 calibre-server --url-prefix /calibre --port 8080
@ -35,7 +35,7 @@ The exact technique for enabling the proxy modules will vary depending on your A
SetEnv force-proxy-request-1.0 1 SetEnv force-proxy-request-1.0 1
SetEnv proxy-nokeepalive 1 SetEnv proxy-nokeepalive 1
That's all, you will now be able to access the |app| Content Server under the /calibre URL in your apache server. The above rules pass all requests under /calibre to the calibre server running on port 8080 and thanks to the --url-prefix option above, the calibre server handles them transparently. That's all, you will now be able to access the calibre Content Server under the /calibre URL in your apache server. The above rules pass all requests under /calibre to the calibre server running on port 8080 and thanks to the --url-prefix option above, the calibre server handles them transparently.
.. note:: If you are willing to devote an entire VirtualHost to the content server, then there is no need to use --url-prefix and RewriteRule, instead just use the ProxyPass directive. .. note:: If you are willing to devote an entire VirtualHost to the content server, then there is no need to use --url-prefix and RewriteRule, instead just use the ProxyPass directive.
@ -110,7 +110,7 @@ The exact technique for enabling the wsgi module will vary depending on your Apa
Change the path to :file:`calibre-wsgi-adapter.py` to wherever you saved it previously (make sure Apache has access to it). Change the path to :file:`calibre-wsgi-adapter.py` to wherever you saved it previously (make sure Apache has access to it).
That's all, you will now be able to access the |app| Content Server under the /calibre URL in your apache server. That's all, you will now be able to access the calibre Content Server under the /calibre URL in your apache server.
.. note:: For more help with using mod_wsgi in Apache, see `mod_wsgi <http://code.google.com/p/modwsgi/wiki/WhereToGetHelp>`_. .. note:: For more help with using mod_wsgi in Apache, see `mod_wsgi <http://code.google.com/p/modwsgi/wiki/WhereToGetHelp>`_.

10
manual/simple_index.rst
View File

@ -1,17 +1,17 @@
=============================================== ===============================================
|app| User Manual calibre User Manual
=============================================== ===============================================
|app| is an ebook library manager. It can view, convert and catalog ebooks in most of the major ebook formats. It can also talk to many ebook reader devices. It can go out to the Internet and fetch metadata for your books. It can download newspapers and convert them into ebooks for convenient reading. It is cross platform, running on Linux, Windows and OS X. calibre is an ebook library manager. It can view, convert and catalog ebooks in most of the major ebook formats. It can also talk to many ebook reader devices. It can go out to the Internet and fetch metadata for your books. It can download newspapers and convert them into ebooks for convenient reading. It is cross platform, running on Linux, Windows and OS X.
You've just started |app|. What do you do now? Before |app| can do anything with your ebooks, it first has to know about them. Drag and drop a few ebook files into |app|, or click the "Add books" button and browse for the ebooks you want to work with. Once you've added the books, they will show up in the main view looking something like this: You've just started calibre. What do you do now? Before calibre can do anything with your ebooks, it first has to know about them. Drag and drop a few ebook files into calibre, or click the "Add books" button and browse for the ebooks you want to work with. Once you've added the books, they will show up in the main view looking something like this:
.. image:: images/added_books.png .. image:: images/added_books.png
Once you've admired the list of books you just added to your heart's content, you'll probably want to read one. In order to do that you'll have to convert the book to a format your reader understands. When first running |app|, the Welcome Wizard starts and will set up calibre for your reader device. Conversion is a breeze. Just select the book you want to convert then click the "Convert books" button. Ignore all the options for now and click "OK". The little icon in the bottom right corner will start spinning. Once it's finished spinning, your converted book is ready. Click the "View" button to read the book. Once you've admired the list of books you just added to your heart's content, you'll probably want to read one. In order to do that you'll have to convert the book to a format your reader understands. When first running calibre, the Welcome Wizard starts and will set up calibre for your reader device. Conversion is a breeze. Just select the book you want to convert then click the "Convert books" button. Ignore all the options for now and click "OK". The little icon in the bottom right corner will start spinning. Once it's finished spinning, your converted book is ready. Click the "View" button to read the book.
If you want to read the book on your reader, connect it to the computer, wait till calibre detects it (10-20 seconds) and then click the "Send to device" button. Once the icon stops spinning again, disconnect your reader and read away! If you didn't convert the book in the previous step, |app| will auto convert it to the format your reader device understands. If you want to read the book on your reader, connect it to the computer, wait till calibre detects it (10-20 seconds) and then click the "Send to device" button. Once the icon stops spinning again, disconnect your reader and read away! If you didn't convert the book in the previous step, calibre will auto convert it to the format your reader device understands.
To get started with more advanced usage, you should read about the :ref:`Graphical User Interface <gui>`. For even more power and versatility, learn the :ref:`Command Line Interface <cli>`. You will find the list of :ref:`Frequently Asked Questions <faq>` useful as well. To get started with more advanced usage, you should read about the :ref:`Graphical User Interface <gui>`. For even more power and versatility, learn the :ref:`Command Line Interface <cli>`. You will find the list of :ref:`Frequently Asked Questions <faq>` useful as well.

12
manual/sub_groups.rst
View File

@ -5,7 +5,7 @@ Managing subgroups of books, for example "genre"
Some people wish to organize the books in their library into subgroups, similar to subfolders. The most commonly provided reason is to create genre hierarchies, but there are many others. One user asked for a way to organize textbooks by subject and course number. Another wanted to keep track of gifts by subject and recipient. This tutorial will use the genre example for the rest of this post. Some people wish to organize the books in their library into subgroups, similar to subfolders. The most commonly provided reason is to create genre hierarchies, but there are many others. One user asked for a way to organize textbooks by subject and course number. Another wanted to keep track of gifts by subject and recipient. This tutorial will use the genre example for the rest of this post.
Before going on, please note that we are not talking about folders on the hard disk. Subgroups are not file folders. Books will not be copied anywhere. Calibre's library file structure is not affected. Instead, we are presenting a way to organize and display subgroups of books within a |app| library. Before going on, please note that we are not talking about folders on the hard disk. Subgroups are not file folders. Books will not be copied anywhere. Calibre's library file structure is not affected. Instead, we are presenting a way to organize and display subgroups of books within a calibre library.
.. contents:: .. contents::
:depth: 1 :depth: 1
@ -17,7 +17,7 @@ Before going on, please note that we are not talking about folders on the hard d
The commonly-provided requirements for subgroups such as genres are: The commonly-provided requirements for subgroups such as genres are:
* A subgroup (e.g., a genre) must contain (point to) books, not categories of books. This is what distinguishes subgroups from |app| user categories. * A subgroup (e.g., a genre) must contain (point to) books, not categories of books. This is what distinguishes subgroups from calibre user categories.
* A book can be in multiple subgroups (genres). This distinguishes subgroups from physical file folders. * A book can be in multiple subgroups (genres). This distinguishes subgroups from physical file folders.
* Subgroups (genres) must form a hierarchy; subgroups can contain subgroups. * Subgroups (genres) must form a hierarchy; subgroups can contain subgroups.
@ -53,19 +53,19 @@ Once a genre exists, that is at least one book has that genre, you can easily ap
Setup Setup
---------------------------------------- ----------------------------------------
By now, your question might be "How was all of this up?" There are three steps: 1) create the custom column, 2) tell |app| that the new column is to be treated as a hierarchy, and 3) add genres. By now, your question might be "How was all of this up?" There are three steps: 1) create the custom column, 2) tell calibre that the new column is to be treated as a hierarchy, and 3) add genres.
You create the custom column in the usual way, using Preferences -> Add your own columns. This example uses "#genre" as the lookup name and "Genre" as the column heading. The column type is "Comma-separated text, like tags, shown in the tag browser." You create the custom column in the usual way, using Preferences -> Add your own columns. This example uses "#genre" as the lookup name and "Genre" as the column heading. The column type is "Comma-separated text, like tags, shown in the tag browser."
.. image:: images/sg_cc.jpg .. image:: images/sg_cc.jpg
:align: center :align: center
Then after restarting |app|, you must tell |app| that the column is to be treated as a hierarchy. Go to Preferences -> Look and Feel -> Tag Browser and enter the lookup name "#genre" into the "Categories with hierarchical items" box. Press Apply, and you are done with setting up. Then after restarting calibre, you must tell calibre that the column is to be treated as a hierarchy. Go to Preferences -> Look and Feel -> Tag Browser and enter the lookup name "#genre" into the "Categories with hierarchical items" box. Press Apply, and you are done with setting up.
.. image:: images/sg_pref.png .. image:: images/sg_pref.png
:align: center :align: center
At the point there are no genres in the column. We are left with the last step: how to apply a genre to a book. A genre does not exist in |app| until it appears on at least one book. To learn how to apply a genre for the first time, we must go into some detail about what a genre looks like in the metadata for a book. At the point there are no genres in the column. We are left with the last step: how to apply a genre to a book. A genre does not exist in calibre until it appears on at least one book. To learn how to apply a genre for the first time, we must go into some detail about what a genre looks like in the metadata for a book.
A hierarchy of 'things' is built by creating an item consisting of phrases separated by periods. Continuing the genre example, these items would "History.Military", "Mysteries.Vampire", "Science Fiction.Space Opera", etc. Thus to create a new genre, you pick a book that should have that genre, edit its metadata, and enter the new genre into the column you created. Continuing our example, if you want to assign a new genre "Comics" with a sub-genre "Superheroes" to a book, you would 'edit metadata' for that (comic) book, choose the Custom metadata tab, and then enter "Comics.Superheroes" as shown in the following (ignore the other custom columns): A hierarchy of 'things' is built by creating an item consisting of phrases separated by periods. Continuing the genre example, these items would "History.Military", "Mysteries.Vampire", "Science Fiction.Space Opera", etc. Thus to create a new genre, you pick a book that should have that genre, edit its metadata, and enter the new genre into the column you created. Continuing our example, if you want to assign a new genre "Comics" with a sub-genre "Superheroes" to a book, you would 'edit metadata' for that (comic) book, choose the Custom metadata tab, and then enter "Comics.Superheroes" as shown in the following (ignore the other custom columns):
@ -105,7 +105,7 @@ After creating the saved search, you can use it as a restriction.
Useful Template Functions Useful Template Functions
------------------------- -------------------------
You might want to use the genre information in a template, such as with save to disk or send to device. The question might then be "How do I get the outermost genre name or names?" A |app| template function, subitems, is provided to make doing this easier. You might want to use the genre information in a template, such as with save to disk or send to device. The question might then be "How do I get the outermost genre name or names?" A calibre template function, subitems, is provided to make doing this easier.
For example, assume you want to add the outermost genre level to the save-to-disk template to make genre folders, as in "History/The Gathering Storm - Churchill, Winston". To do this, you must extract the first level of the hierarchy and add it to the front along with a slash to indicate that it should make a folder. The template below accomplishes this:: For example, assume you want to add the outermost genre level to the save-to-disk template to make genre folders, as in "History/The Gathering Storm - Churchill, Winston". To do this, you must extract the first level of the hierarchy and add it to the front along with a slash to indicate that it should make a folder. The template below accomplishes this::

22
manual/template_lang.rst
View File

@ -1,12 +1,12 @@
.. _templatelangcalibre: .. _templatelangcalibre:
The |app| template language The calibre template language
======================================================= =======================================================
The |app| template language is used in various places. It is used to control the folder structure and file name when saving files from the |app| library to the disk or eBook reader. The calibre template language is used in various places. It is used to control the folder structure and file name when saving files from the calibre library to the disk or eBook reader.
It is also used to define "virtual" columns that contain data from other columns and so on. It is also used to define "virtual" columns that contain data from other columns and so on.
The basic template language is very simple, but has very powerful advanced features. The basic idea is that a template consists of text and names in curly brackets that are then replaced by the corresponding metadata from the book being processed. So, for example, the default template used for saving books to device in |app| is:: The basic template language is very simple, but has very powerful advanced features. The basic idea is that a template consists of text and names in curly brackets that are then replaced by the corresponding metadata from the book being processed. So, for example, the default template used for saving books to device in calibre is::
{author_sort}/{title}/{title} - {authors} {author_sort}/{title}/{title} - {authors}
@ -41,7 +41,7 @@ and if a book does not have a series::
Asimov, Isaac/Second Foundation Asimov, Isaac/Second Foundation
(|app| automatically removes multiple slashes and leading or trailing spaces). (calibre automatically removes multiple slashes and leading or trailing spaces).
Advanced formatting Advanced formatting
---------------------- ----------------------
@ -84,7 +84,7 @@ If you want only the first two letters of the data, use::
{author_sort:.2} - Only the first two letter of the author sort name {author_sort:.2} - Only the first two letter of the author sort name
The |app| template language comes from python and for more details on the syntax of these advanced formatting operations, look at the `Python documentation <http://docs.python.org/library/string.html#format-string-syntax>`_. The calibre template language comes from python and for more details on the syntax of these advanced formatting operations, look at the `Python documentation <http://docs.python.org/library/string.html#format-string-syntax>`_.
Advanced features Advanced features
------------------ ------------------
@ -92,7 +92,7 @@ Advanced features
Using templates in custom columns Using templates in custom columns
---------------------------------- ----------------------------------
There are sometimes cases where you want to display metadata that |app| does not normally display, or to display data in a way different from how |app| normally does. For example, you might want to display the ISBN, a field that |app| does not display. You can use custom columns for this by creating a column with the type 'column built from other columns' (hereafter called composite columns), and entering a template. Result: |app| will display a column showing the result of evaluating that template. To display the ISBN, create the column and enter ``{identifiers:select(isbn)}`` into the template box. To display a column containing the values of two series custom columns separated by a comma, use ``{#series1:||,}{#series2}``. There are sometimes cases where you want to display metadata that calibre does not normally display, or to display data in a way different from how calibre normally does. For example, you might want to display the ISBN, a field that calibre does not display. You can use custom columns for this by creating a column with the type 'column built from other columns' (hereafter called composite columns), and entering a template. Result: calibre will display a column showing the result of evaluating that template. To display the ISBN, create the column and enter ``{identifiers:select(isbn)}`` into the template box. To display a column containing the values of two series custom columns separated by a comma, use ``{#series1:||,}{#series2}``.
Composite columns can use any template option, including formatting. Composite columns can use any template option, including formatting.
@ -129,7 +129,7 @@ The functions available are listed below. Note that the definitive documentation
* ``language_strings(lang_codes, localize)`` -- return the strings for the language codes passed in `lang_codes`. If `localize` is zero, return the strings in English. If localize is not zero, return the strings in the language of the current locale. `Lang_codes` is a comma-separated list. * ``language_strings(lang_codes, localize)`` -- return the strings for the language codes passed in `lang_codes`. If `localize` is zero, return the strings in English. If localize is not zero, return the strings in the language of the current locale. `Lang_codes` is a comma-separated list.
* ``list_item(index, separator)`` -- interpret the field as a list of items separated by `separator`, returning the `index`th item. The first item is number zero. The last item can be returned using `list_item(-1,separator)`. If the item is not in the list, then the empty value is returned. The separator has the same meaning as in the `count` function. * ``list_item(index, separator)`` -- interpret the field as a list of items separated by `separator`, returning the `index`th item. The first item is number zero. The last item can be returned using `list_item(-1,separator)`. If the item is not in the list, then the empty value is returned. The separator has the same meaning as in the `count` function.
* ``lookup(pattern, field, pattern, field, ..., else_field)`` -- like switch, except the arguments are field (metadata) names, not text. The value of the appropriate field will be fetched and used. Note that because composite columns are fields, you can use this function in one composite field to use the value of some other composite field. This is extremely useful when constructing variable save paths (more later). * ``lookup(pattern, field, pattern, field, ..., else_field)`` -- like switch, except the arguments are field (metadata) names, not text. The value of the appropriate field will be fetched and used. Note that because composite columns are fields, you can use this function in one composite field to use the value of some other composite field. This is extremely useful when constructing variable save paths (more later).
* ``re(pattern, replacement)`` -- return the field after applying the regular expression. All instances of `pattern` are replaced with `replacement`. As in all of |app|, these are python-compatible regular expressions. * ``re(pattern, replacement)`` -- return the field after applying the regular expression. All instances of `pattern` are replaced with `replacement`. As in all of calibre, these are python-compatible regular expressions.
* ``select(key)`` -- interpret the field as a comma-separated list of items, with the items being of the form "id:value". Find the pair with the id equal to key, and return the corresponding value. This function is particularly useful for extracting a value such as an isbn from the set of identifiers for a book. * ``select(key)`` -- interpret the field as a comma-separated list of items, with the items being of the form "id:value". Find the pair with the id equal to key, and return the corresponding value. This function is particularly useful for extracting a value such as an isbn from the set of identifiers for a book.
* ``shorten(left chars, middle text, right chars)`` -- Return a shortened version of the field, consisting of `left chars` characters from the beginning of the field, followed by `middle text`, followed by `right chars` characters from the end of the string. `Left chars` and `right chars` must be integers. For example, assume the title of the book is `Ancient English Laws in the Times of Ivanhoe`, and you want it to fit in a space of at most 15 characters. If you use ``{title:shorten(9,-,5)}``, the result will be `Ancient E-nhoe`. If the field's length is less than ``left chars`` + ``right chars`` + the length of ``middle text``, then the field will be used intact. For example, the title `The Dome` would not be changed. * ``shorten(left chars, middle text, right chars)`` -- Return a shortened version of the field, consisting of `left chars` characters from the beginning of the field, followed by `middle text`, followed by `right chars` characters from the end of the string. `Left chars` and `right chars` must be integers. For example, assume the title of the book is `Ancient English Laws in the Times of Ivanhoe`, and you want it to fit in a space of at most 15 characters. If you use ``{title:shorten(9,-,5)}``, the result will be `Ancient E-nhoe`. If the field's length is less than ``left chars`` + ``right chars`` + the length of ``middle text``, then the field will be used intact. For example, the title `The Dome` would not be changed.
* ``str_in_list(val, separator, string, found_val, not_found_val)`` -- treat val as a list of items separated by separator, comparing the string against each value in the list. If the string matches a value, return found_val, otherwise return not_found_val. If the string contains separators, then it is also treated as a list and each value is checked. * ``str_in_list(val, separator, string, found_val, not_found_val)`` -- treat val as a list of items separated by separator, comparing the string against each value in the list. If the string matches a value, return found_val, otherwise return not_found_val. If the string contains separators, then it is also treated as a list and each value is checked.
@ -241,7 +241,7 @@ The following functions are available in addition to those described in single-f
* ``approximate_formats()`` -- return a comma-separated list of formats that at one point were associated with the book. There is no guarantee that the list is correct, although it probably is. This function can be called in template program mode using the template ``{:'approximate_formats()'}``. Note that format names are always uppercase, as in EPUB. * ``approximate_formats()`` -- return a comma-separated list of formats that at one point were associated with the book. There is no guarantee that the list is correct, although it probably is. This function can be called in template program mode using the template ``{:'approximate_formats()'}``. Note that format names are always uppercase, as in EPUB.
* ``author_links(val_separator, pair_separator)`` -- returns a string containing a list of authors and that author's link values in the form ``author1 val_separator author1link pair_separator author2 val_separator author2link`` etc. An author is separated from its link value by the ``val_separator`` string with no added spaces. ``author:linkvalue`` pairs are separated by the ``pair_separator`` string argument with no added spaces. It is up to you to choose separator strings that do not occur in author names or links. An author is included even if the author link is empty. * ``author_links(val_separator, pair_separator)`` -- returns a string containing a list of authors and that author's link values in the form ``author1 val_separator author1link pair_separator author2 val_separator author2link`` etc. An author is separated from its link value by the ``val_separator`` string with no added spaces. ``author:linkvalue`` pairs are separated by the ``pair_separator`` string argument with no added spaces. It is up to you to choose separator strings that do not occur in author names or links. An author is included even if the author link is empty.
* ``author_sorts(val_separator)`` -- returns a string containing a list of author's sort values for the authors of the book. The sort is the one in the author metadata (different from the author_sort in books). The returned list has the form author sort 1 ``val_separator`` author sort 2 etc. The author sort values in this list are in the same order as the authors of the book. If you want spaces around ``val_separator`` then include them in the separator string * ``author_sorts(val_separator)`` -- returns a string containing a list of author's sort values for the authors of the book. The sort is the one in the author metadata (different from the author_sort in books). The returned list has the form author sort 1 ``val_separator`` author sort 2 etc. The author sort values in this list are in the same order as the authors of the book. If you want spaces around ``val_separator`` then include them in the separator string
* ``booksize()`` -- returns the value of the |app| 'size' field. Returns '' if there are no formats. * ``booksize()`` -- returns the value of the calibre 'size' field. Returns '' if there are no formats.
* ``cmp(x, y, lt, eq, gt)`` -- compares x and y after converting both to numbers. Returns ``lt`` if x < y. Returns ``eq`` if x == y. Otherwise returns ``gt``. * ``cmp(x, y, lt, eq, gt)`` -- compares x and y after converting both to numbers. Returns ``lt`` if x < y. Returns ``eq`` if x == y. Otherwise returns ``gt``.
* ``current_library_name() -- `` return the last name on the path to the current calibre library. This function can be called in template program mode using the template ``{:'current_library_name()'}``. * ``current_library_name() -- `` return the last name on the path to the current calibre library. This function can be called in template program mode using the template ``{:'current_library_name()'}``.
* ``current_library_path() -- `` return the path to the current calibre library. This function can be called in template program mode using the template ``{:'current_library_path()'}``.. * ``current_library_path() -- `` return the path to the current calibre library. This function can be called in template program mode using the template ``{:'current_library_path()'}``..
@ -340,7 +340,7 @@ Function classification
Using general program mode Using general program mode
----------------------------------- -----------------------------------
For more complicated template programs, it is sometimes easier to avoid template syntax (all the `{` and `}` characters), instead writing a more classical-looking program. You can do this in |app| by beginning the template with `program:`. In this case, no template processing is done. The special variable `$` is not set. It is up to your program to produce the correct results. For more complicated template programs, it is sometimes easier to avoid template syntax (all the `{` and `}` characters), instead writing a more classical-looking program. You can do this in calibre by beginning the template with `program:`. In this case, no template processing is done. The special variable `$` is not set. It is up to your program to produce the correct results.
One advantage of `program:` mode is that the brackets are no longer special. For example, it is not necessary to use `[[` and `]]` when using the `template()` function. Another advantage is that program mode templates are compiled to Python and can run much faster than templates in the other two modes. Speed improvement depends on the complexity of the templates; the more complicated the template the more the improvement. Compilation is turned off or on using the tweak ``compile_gpm_templates`` (Compile General Program Mode templates to Python). The main reason to turn off compilation is if a compiled template does not work, in which case please file a bug report. One advantage of `program:` mode is that the brackets are no longer special. For example, it is not necessary to use `[[` and `]]` when using the `template()` function. Another advantage is that program mode templates are compiled to Python and can run much faster than templates in the other two modes. Speed improvement depends on the complexity of the templates; the more complicated the template the more the improvement. Compilation is turned off or on using the tweak ``compile_gpm_templates`` (Compile General Program Mode templates to Python). The main reason to turn off compilation is if a compiled template does not work, in which case please file a bug report.
@ -455,14 +455,14 @@ Plugboards are used for changing the metadata written into books during send-to-
When you create a plugboard, you specify the format and device for which the plugboard is to be used. A special device is provided, save_to_disk, that is used when saving formats (as opposed to sending them to a device). Once you have chosen the format and device, you choose the metadata fields to change, providing templates to supply the new values. These templates are `connected` to their destination fields, hence the name `plugboards`. You can, of course, use composite columns in these templates. When you create a plugboard, you specify the format and device for which the plugboard is to be used. A special device is provided, save_to_disk, that is used when saving formats (as opposed to sending them to a device). Once you have chosen the format and device, you choose the metadata fields to change, providing templates to supply the new values. These templates are `connected` to their destination fields, hence the name `plugboards`. You can, of course, use composite columns in these templates.
When a plugboard might apply (content server, save to disk, or send to device), |app| searches the defined plugboards to choose the correct one for the given format and device. For example, to find the appropriate plugboard for an EPUB book being sent to an ANDROID device, |app| searches the plugboards using the following search order: When a plugboard might apply (content server, save to disk, or send to device), calibre searches the defined plugboards to choose the correct one for the given format and device. For example, to find the appropriate plugboard for an EPUB book being sent to an ANDROID device, calibre searches the plugboards using the following search order:
* a plugboard with an exact match on format and device, e.g., ``EPUB`` and ``ANDROID`` * a plugboard with an exact match on format and device, e.g., ``EPUB`` and ``ANDROID``
* a plugboard with an exact match on format and the special ``any device`` choice, e.g., ``EPUB`` and ``any device`` * a plugboard with an exact match on format and the special ``any device`` choice, e.g., ``EPUB`` and ``any device``
* a plugboard with the special ``any format`` choice and an exact match on device, e.g., ``any format`` and ``ANDROID`` * a plugboard with the special ``any format`` choice and an exact match on device, e.g., ``any format`` and ``ANDROID``
* a plugboard with ``any format`` and ``any device`` * a plugboard with ``any format`` and ``any device``
The tags and authors fields have special treatment, because both of these fields can hold more than one item. A book can have many tags and many authors. When you specify that one of these two fields is to be changed, the template's result is examined to see if more than one item is there. For tags, the result is cut apart wherever |app| finds a comma. For example, if the template produces the value ``Thriller, Horror``, then the result will be two tags, ``Thriller`` and ``Horror``. There is no way to put a comma in the middle of a tag. The tags and authors fields have special treatment, because both of these fields can hold more than one item. A book can have many tags and many authors. When you specify that one of these two fields is to be changed, the template's result is examined to see if more than one item is there. For tags, the result is cut apart wherever calibre finds a comma. For example, if the template produces the value ``Thriller, Horror``, then the result will be two tags, ``Thriller`` and ``Horror``. There is no way to put a comma in the middle of a tag.
The same thing happens for authors, but using a different character for the cut, a `&` (ampersand) instead of a comma. For example, if the template produces the value ``Blogs, Joe&Posts, Susan``, then the book will end up with two authors, ``Blogs, Joe`` and ``Posts, Susan``. If the template produces the value ``Blogs, Joe;Posts, Susan``, then the book will have one author with a rather strange name. The same thing happens for authors, but using a different character for the cut, a `&` (ampersand) instead of a comma. For example, if the template produces the value ``Blogs, Joe&Posts, Susan``, then the book will end up with two authors, ``Blogs, Joe`` and ``Posts, Susan``. If the template produces the value ``Blogs, Joe;Posts, Susan``, then the book will have one author with a rather strange name.

2
manual/template_ref_generate.py
View File

@ -12,7 +12,7 @@ PREAMBLE = '''\
Reference for all built-in template language functions Reference for all built-in template language functions
======================================================== ========================================================
Here, we document all the built-in functions available in the |app| template language. Every function is implemented as a class in python and you can click the source links to see the source code, in case the documentation is insufficient. The functions are arranged in logical groups by type. Here, we document all the built-in functions available in the calibre template language. Every function is implemented as a class in python and you can click the source links to see the source code, in case the documentation is insufficient. The functions are arranged in logical groups by type.
.. contents:: .. contents::
:depth: 2 :depth: 2

2
manual/tutorials.rst
View File

@ -3,7 +3,7 @@
Tutorials Tutorials
======================================================= =======================================================
Here you will find tutorials to get you started using |app|'s more advanced features, such as XPath and templates. Here you will find tutorials to get you started using calibre's more advanced features, such as XPath and templates.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1

16
manual/typesetting_math.rst
View File

@ -4,23 +4,23 @@
Typesetting Math in ebooks Typesetting Math in ebooks
============================ ============================
The |app| ebook viewer has the ability to display math embedded in ebooks (ePub The calibre ebook viewer has the ability to display math embedded in ebooks (ePub
and HTML files). You can typeset the math directly with TeX or MathML or and HTML files). You can typeset the math directly with TeX or MathML or
AsciiMath. The |app| viewer uses the excellent `MathJax AsciiMath. The calibre viewer uses the excellent `MathJax
<http://www.mathjax.org>`_ library to do this. This is a brief tutorial on <http://www.mathjax.org>`_ library to do this. This is a brief tutorial on
creating ebooks with math in them that work well with the |app| viewer. creating ebooks with math in them that work well with the calibre viewer.
A simple HTML file with mathematics A simple HTML file with mathematics
------------------------------------- -------------------------------------
You can write mathematics inline inside a simple HTML file and the |app| viewer You can write mathematics inline inside a simple HTML file and the calibre viewer
will render it into properly typeset mathematics. In the example below, we use will render it into properly typeset mathematics. In the example below, we use
TeX notation for mathematics. You will see that you can use normal TeX TeX notation for mathematics. You will see that you can use normal TeX
commands, with the small caveat that ampersands and less than and greater than commands, with the small caveat that ampersands and less than and greater than
signs have to be written as &amp; &lt; and &gt; respectively. signs have to be written as &amp; &lt; and &gt; respectively.
The first step is to tell |app| that this will contains maths. You do this by The first step is to tell calibre that this will contains maths. You do this by
adding the following snippet of code to the <head> section of the HTML file:: adding the following snippet of code to the <head> section of the HTML file::
<script type="text/x-mathjax-config"></script> <script type="text/x-mathjax-config"></script>
@ -38,7 +38,7 @@ example, here are Lorentz's equations::
\end{align} \end{align}
</p> </p>
This snippet looks like the following screen shot in the |app| viewer. This snippet looks like the following screen shot in the calibre viewer.
.. figure:: images/lorentz.png .. figure:: images/lorentz.png
:align: center :align: center
@ -46,7 +46,7 @@ This snippet looks like the following screen shot in the |app| viewer.
:guilabel:`The Lorenz Equations` :guilabel:`The Lorenz Equations`
The complete HTML file, with more equations and inline mathematics is The complete HTML file, with more equations and inline mathematics is
reproduced below. You can convert this HTML file to EPUB in |app| to end up reproduced below. You can convert this HTML file to EPUB in calibre to end up
with an ebook you can distribute easily to other people. with an ebook you can distribute easily to other people.
.. only:: online .. only:: online
@ -59,7 +59,7 @@ with an ebook you can distribute easily to other people.
More information More information
----------------- -----------------
Since the |app| viewer uses the MathJax library to render mathematics, the best Since the calibre viewer uses the MathJax library to render mathematics, the best
place to find out more about math in ebooks and get help is the `MathJax place to find out more about math in ebooks and get help is the `MathJax
website <http://www.mathjax.org>`_. website <http://www.mathjax.org>`_.

14
manual/viewer.rst
View File

@ -3,7 +3,7 @@
The Ebook Viewer The Ebook Viewer
============================= =============================
|app| includes a built-in ebook viewer that can view all the major ebook formats. calibre includes a built-in ebook viewer that can view all the major ebook formats.
The viewer is highly customizable and has many advanced features. The viewer is highly customizable and has many advanced features.
.. contents:: .. contents::
@ -13,7 +13,7 @@ The viewer is highly customizable and has many advanced features.
Starting the viewer Starting the viewer
-------------------- --------------------
You can view any of the books in your |app| library by selecting the book and pressing the View button. This You can view any of the books in your calibre library by selecting the book and pressing the View button. This
will open up the book in the ebook viewer. You can also launch the viewer by itself from the Start menu in Windows will open up the book in the ebook viewer. You can also launch the viewer by itself from the Start menu in Windows
or using the command :command:`ebook-viewer` in Linux and OS X (you have to install the command line tools on OS X or using the command :command:`ebook-viewer` in Linux and OS X (you have to install the command line tools on OS X
first by going to :guilabel:`Preferences->Advanced->Miscellaneous`). first by going to :guilabel:`Preferences->Advanced->Miscellaneous`).
@ -33,7 +33,7 @@ Navigating around an ebook
You can "turn pages" in a book by using the :guilabel:`Page Next` and :guilabel:`Page Previous` buttons |pni|, or by pressing You can "turn pages" in a book by using the :guilabel:`Page Next` and :guilabel:`Page Previous` buttons |pni|, or by pressing
the Page Down/Page Up keys. Unlike most ebook viewers, |app| does not force you to view books in paged mode. You can the Page Down/Page Up keys. Unlike most ebook viewers, calibre does not force you to view books in paged mode. You can
scroll by amounts less than a page by using the scroll bar or various customizable keyboard shortcuts. scroll by amounts less than a page by using the scroll bar or various customizable keyboard shortcuts.
Bookmarks Bookmarks
@ -59,9 +59,9 @@ like this |navposi|. This is both your current position and the total length of
size you are viewing the book at, and they play a similar role to page numbers in paper books. size you are viewing the book at, and they play a similar role to page numbers in paper books.
You can enter any number you like to go to the corresponding location in the book. You can enter any number you like to go to the corresponding location in the book.
|app| also has a very handy calibre also has a very handy
reference mode. You can turn it on by clicking the Reference Mode button |refmi|. Once you do this, every time you move your reference mode. You can turn it on by clicking the Reference Mode button |refmi|. Once you do this, every time you move your
mouse over a paragraph, |app| will display a unique number made up of the section and paragraph numbers. mouse over a paragraph, calibre will display a unique number made up of the section and paragraph numbers.
.. image:: images/ref_mode.png .. image:: images/ref_mode.png
:align: center :align: center
@ -88,12 +88,12 @@ by the viewer to ones you like as well as the default font size when the viewer
More advanced customization can be achieved by the User Stylesheet setting. This is a stylesheet you can set that will be applied More advanced customization can be achieved by the User Stylesheet setting. This is a stylesheet you can set that will be applied
to every book. Using it you can do things like have white text on a black background, change paragraph styles, text justification, etc. to every book. Using it you can do things like have white text on a black background, change paragraph styles, text justification, etc.
For examples of custom stylesheets used by |app|'s users, see `the forums <http://www.mobileread.com/forums/showthread.php?t=51500>`_. For examples of custom stylesheets used by calibre's users, see `the forums <http://www.mobileread.com/forums/showthread.php?t=51500>`_.
Dictionary lookup Dictionary lookup
------------------- -------------------
You can look up the meaning of words in the current book by right clicking on a word. |app| uses the publicly available dictionary You can look up the meaning of words in the current book by right clicking on a word. calibre uses the publicly available dictionary
server at ``dict.org`` to look up words. The definition is displayed in a small box at the bottom of the screen. server at ``dict.org`` to look up words. The definition is displayed in a small box at the bottom of the screen.
Copying text and images Copying text and images

16
manual/virtual_libraries.rst
View File

@ -4,14 +4,14 @@
Virtual Libraries Virtual Libraries
============================ ============================
In |app|, a virtual library is a way to tell |app| to open only a subset of a In calibre, a virtual library is a way to tell calibre to open only a subset of a
normal library. For example, you might want to only work with books by a certain normal library. For example, you might want to only work with books by a certain
author, or books having only a certain tag. Using virtual libraries is the author, or books having only a certain tag. Using virtual libraries is the
preferred way of partitioning your large book collection into smaller sub preferred way of partitioning your large book collection into smaller sub
collections. It is superior to splitting up your library into multiple smaller collections. It is superior to splitting up your library into multiple smaller
libraries as, when you want to search through your entire collection, you can libraries as, when you want to search through your entire collection, you can
simply go back to the full library. There is no way to search through multiple simply go back to the full library. There is no way to search through multiple
separate libraries simultaneously in |app|. separate libraries simultaneously in calibre.
A virtual library is different from a simple search. A search will only restrict A virtual library is different from a simple search. A search will only restrict
the list of books shown in the book list. A virtual library does that, and in the list of books shown in the book list. A virtual library does that, and in
@ -38,7 +38,7 @@ in the image below and choose the author you want to use and click OK.
The Create Virtual Library dialog has been filled in for you. Click OK and you The Create Virtual Library dialog has been filled in for you. Click OK and you
will see that a new Virtual Library has been created, and automatically will see that a new Virtual Library has been created, and automatically
switched to, that displays only the books by the selected author. As far as switched to, that displays only the books by the selected author. As far as
|app| is concerned, it is as if your library contains only the books by the calibre is concerned, it is as if your library contains only the books by the
selected author. selected author.
You can switch back to the full library at any time by once again clicking the You can switch back to the full library at any time by once again clicking the
@ -57,9 +57,9 @@ of things you can do with them, see :ref:`search_interface`.
Examples of useful Virtual Libraries Examples of useful Virtual Libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Books added to |app| in the last day:: * Books added to calibre in the last day::
date:>1daysago date:>1daysago
* Books added to |app| in the last month:: * Books added to calibre in the last month::
date:>30daysago date:>30daysago
* Books with a rating of 5 stars:: * Books with a rating of 5 stars::
rating:5 rating:5
@ -67,7 +67,7 @@ Examples of useful Virtual Libraries
rating:>=4 rating:>=4
* Books with no rating:: * Books with no rating::
rating:false rating:false
* Periodicals downloaded by the Fetch News function in |app|:: * Periodicals downloaded by the Fetch News function in calibre::
tags:=News and author:=calibre tags:=News and author:=calibre
* Books with no tags:: * Books with no tags::
tags:false tags:false
@ -80,11 +80,11 @@ Working with Virtual Libraries
You can edit a previously created virtual library or remove it, by clicking the You can edit a previously created virtual library or remove it, by clicking the
:guilabel:`Virtual Library` and choosing the appropriate action. :guilabel:`Virtual Library` and choosing the appropriate action.
You can tell |app| that you always want to apply a particular virtual library You can tell calibre that you always want to apply a particular virtual library
when the current library is opened, by going to when the current library is opened, by going to
:guilabel:`Preferences->Behavior`. :guilabel:`Preferences->Behavior`.
If you use the |app| Content Server, you can have it share a virtual library If you use the calibre Content Server, you can have it share a virtual library
instead of the full library by going to :guilabel:`Preferences->Sharing over the net`. instead of the full library by going to :guilabel:`Preferences->Sharing over the net`.
You can quickly use the current search as a temporary virtual library by You can quickly use the current search as a temporary virtual library by

4
manual/xpath.rst
View File

@ -6,7 +6,7 @@ XPath Tutorial
In this tutorial, you will be given a gentle introduction to In this tutorial, you will be given a gentle introduction to
`XPath <http://en.wikipedia.org/wiki/XPath>`_, a query language that can be `XPath <http://en.wikipedia.org/wiki/XPath>`_, a query language that can be
used to select arbitrary parts of `HTML <http://en.wikipedia.org/wiki/HTML>`_ used to select arbitrary parts of `HTML <http://en.wikipedia.org/wiki/HTML>`_
documents in |app|. XPath is a widely documents in calibre. XPath is a widely
used standard, and googling it will yield a ton of information. This tutorial, used standard, and googling it will yield a ton of information. This tutorial,
however, focuses on using XPath for ebook related tasks like finding chapter however, focuses on using XPath for ebook related tasks like finding chapter
headings in an unstructured HTML document. headings in an unstructured HTML document.
@ -39,7 +39,7 @@ the prefix::
This will match only ``<p>A very short ebook to demonstrate the use of XPath.</p>`` This will match only ``<p>A very short ebook to demonstrate the use of XPath.</p>``
in the :ref:`sample_ebook` but not any of the other ``<p>`` tags. The ``h:`` prefix in the :ref:`sample_ebook` but not any of the other ``<p>`` tags. The ``h:`` prefix
in the above examples is needed to match XHTML tags. This is because internally, in the above examples is needed to match XHTML tags. This is because internally,
|app| represents all content as XHTML. In XHTML tags have a *namespace*, and calibre represents all content as XHTML. In XHTML tags have a *namespace*, and
``h:`` is the namespace prefix for HTML tags. ``h:`` is the namespace prefix for HTML tags.
Now suppose you want to select both ``<h1>`` and ``<h2>`` tags. To do that, Now suppose you want to select both ``<h1>`` and ``<h2>`` tags. To do that,

2
src/calibre/linux.py
View File

@ -1102,7 +1102,7 @@ def main():
def cli_index_strings(): def cli_index_strings():
return _('Command Line Interface'), _( return _('Command Line Interface'), _(
'On OS X, the command line tools are inside the |app| bundle, for example,' 'On OS X, the command line tools are inside the calibre bundle, for example,'
' if you installed calibre in :file:`/Applications` the command line tools' ' if you installed calibre in :file:`/Applications` the command line tools'
' are in :file:`/Applications/calibre.app/Contents/console.app/Contents/MacOS/`.'), _( ' are in :file:`/Applications/calibre.app/Contents/console.app/Contents/MacOS/`.'), _(
'Documented Commands'), _('Undocumented Commands'), _( 'Documented Commands'), _('Undocumented Commands'), _(