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

misc. typos, fix accidental nesting in template docs.

Browse Source
This commit is contained in:
Eli Schwartz 2015-08-27 18:43:31 -04:00 committed by Kovid Goyal
parent e64f766890
commit 95917bfcd1
11 changed files with 147 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
manual/creating_plugins.rst
View File

@ -19,7 +19,7 @@ Anatomy of a calibre plugin
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,
let's see a basic example.
let's see a basic example.
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 calibre to have their publisher set as "Hello world", here's how to do it.
@ -34,15 +34,15 @@ the directory in which you created :file:`__init__.py`::
calibre-customize -b .
.. note::
.. note::
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
are in :file:`/Applications/calibre.app/Contents/console.app/Contents/MacOS/`.
You can download the Hello World plugin from
`helloworld_plugin.zip <http://calibre-ebook.com/downloads/helloworld_plugin.zip>`_.
You can download the Hello World plugin from
`helloworld_plugin.zip <http://calibre-ebook.com/downloads/helloworld_plugin.zip>`_.
Every time you use calibre to convert a book, the plugin's :meth:`run` method will be called and the
Every time you use calibre to convert a book, the plugin's :meth:`run` method will be called and the
converted book will have its publisher set to "Hello World". This is a trivial plugin, lets move on to
a more complex example that actually adds a component to the user interface.
@ -50,9 +50,9 @@ 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
(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 calibre user interface and how to access
and query the books database in calibre.
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>`_
@ -65,13 +65,13 @@ The first thing to note is that this zip file has a lot more files in it, explai
An empty text file used to enable the multi-file plugin magic. This file must be present in all plugins that use
more than one .py file. It should be empty and its filename must be of the form: plugin-import-name-**some_name**.txt
The presence of this file allows you to import code from the .py files present inside the zip file, using a statement like::
from calibre_plugins.some_name.some_module import some_object
The prefix ``calibre_plugins`` must always be present. ``some_name`` comes from the filename of the empty text file.
``some_module`` refers to :file:`some_module.py` file inside the zip file. Note that this importing is just as
powerful as regular python imports. You can create packages and subpackages of .py modules inside the zip file,
just like you would normally (by defining __init__.py in each sub directory), and everything should Just Work.
just like you would normally (by defining __init__.py in each sub-directory), and everything should Just Work.
The name you use for ``some_name`` enters a global namespace shared by all plugins, **so make it as unique as possible**.
But remember that it must be a valid python identifier (only alphabets, numbers and the underscore).
@ -109,12 +109,12 @@ First, the obligatory ``__init__.py`` to define the plugin metadata:
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,
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,
as discussed above.
Also there are a couple of methods for enabling user configuration of the plugin. These are discussed below.
Also there are a couple of methods for enabling user configuration of the plugin. These are discussed below.
ui.py
^^^^^^^^
@ -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
:pyobject: InterfacePluginDemo.save_settings
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.
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:
@ -185,11 +185,11 @@ Edit Book plugins
Now let's change gears for a bit and look at creating a plugin to add tools to
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
import name empty txt file, as described :ref:`above <import_name_txt>`.
We shall name the file ``plugin-import-name-editor_plugin_demo.txt``.
We shall name the file ``plugin-import-name-editor_plugin_demo.txt``.
Now we create the mandatory ``__init__.py`` file that contains metadata about
the plugin -- its name, author, version, etc.
@ -261,7 +261,7 @@ visible strings as translatable, by surrounding them in _(). For example::
Then use some program to generate .po files from your plugin source code. There
should be one .po file for every language you want to translate into. For
example: de.po for German, fr.po for French and so on. You can use the
example: de.po for German, fr.po for French and so on. You can use the
`poedit <http://poedit.net/>`_ program for this.
Send these .po files to your translators. Once you get them back, compile them
@ -291,7 +291,7 @@ The plugin API
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`.
Your plugin is almost certainly going to use code from calibre. To learn
Your plugin is almost certainly going to use code from calibre. To learn
how to find various bits of functionality in the
calibre code base, read the section on the calibre :ref:`code_layout`.

49
manual/edit.rst
View File

@ -1,6 +1,6 @@
.. _edit:
Editing E-books
Editing E-books
========================
calibre has an integrated e-book editor that can be used to edit books in the
@ -40,12 +40,12 @@ Tutorial <http://html.net/tutorials/html/>`_ and `CSS Tutorial
As you make changes to the HTML or CSS in the editor, the changes will be
previewed, live, in the preview panel to the right. When you are happy with how
the changes you have made look, click the Save button or use
:guilabel:`File->Save` to save your changes into the ebook.
:guilabel:`File->Save` to save your changes into the ebook.
One useful feature is :guilabel:`Checkpoints`. Before you embark on some
ambitious set of edits, you can create a checkpoint. The checkpoint
will preserve the current state of your book, then if in the future you decide
you dont like the changes you have made to you can go back to the state when
you don't like the changes you have made to you can go back to the state when
you created the checkpoint. To create a checkpoint, use :guilabel:`Edit->Create
checkpoint`. Checkpoints will also be automatically created for you whenever you
run any automated tool like global search and replace. The checkpointing
@ -161,7 +161,7 @@ Export of files
You can export a file from inside the book to somewhere else on your computer.
This is useful if you want to work on the file in isolation, with specialised
tools. To do this, simply right click on the file and choose
:guilabel:`Export`.
:guilabel:`Export`.
Once you are done working on the exported file, you can re-import it into the
book, by right clicking on the file again and choosing :guilabel:`Replace with
@ -195,7 +195,7 @@ right click and choose Link stylesheets to have calibre automatically insert the
<link> tags for those stylesheets into all the selected HTML files.
.. raw:: html epub
<div style="clear:both"></div>
@ -213,16 +213,16 @@ searching, see :ref:`regexptutorial`.
:align: center
Start the search and replace via the :guilabel:`Search->Find/replace` menu
entry (you must be editing an HTML or CSS file).
entry (you must be editing an HTML or CSS file).
Type the text you want to find into the Find box and its replacement into the
Replace box. You can the click the appropriate buttons to Find the next match,
replace the current match and replace all matches.
replace the current match and replace all matches.
Using the drop downs at the bottom of the box, you can have the search operate
over the current file, all text files, all style files or all files. You can
also choose the search mode to be a normal (string) search or a regular
expression search.
expression search.
You can count all the matches for a search expression via
:guilabel:`Search->Count all`. The count will run over whatever files/regions
@ -231,7 +231,7 @@ you have selected in the dropdown box.
You can also go to a specific line in the currently open editor via
:guilabel:`Search->Go to line`.
.. note::
.. note::
Remember, to harness the full power of search and replace, you will
need to use regular expressions. See :ref:`regexptutorial`.
@ -264,7 +264,7 @@ Edit the Table of Contents
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There is a dedicated tool to ease editing of the Table of Contents. Launch it
with :guilabel:`Tools->Table of Contents->Edit Table of Contents`.
with :guilabel:`Tools->Table of Contents->Edit Table of Contents`.
.. image:: images/tocedit.png
:alt: The Edit Table of Contents tool
@ -277,13 +277,13 @@ also re-arrange entries by drag and drop or by using the buttons to the right.
For books that do not have a pre-existing Table of Contents, the tool gives you
various options to auto-generate a Table of Contents from the text. You can
generate from the headings in the document, from links, from individual files
and so on.
and so on.
You can edit individual entries by clicking on them and then clicking the
:guilabel:`Change the location this entry points to` button. This will open up
a mini-preview of the book, simply move the mouse cursor over the book view
panel, and click where you want the entry to point to. A thick green line
will show you the location. Click OK once you are happy with the location.
will show you the location. Click OK once you are happy with the location.
.. image:: images/tocedit-location.png
:alt: The Edit Table of Contents tool, how to change the location an entry points to
@ -380,7 +380,7 @@ Removing unused CSS rules
Remove all unused CSS rules from stylesheets and <style> tags. Some books
created from production templates can have a large number of extra CSS rules
that dont match any actual content. These extra rules can slow down readers
that don't match any actual content. These extra rules can slow down readers
that need to process them all. Accessed via :guilabel:`Tools->Remove unused CSS`.
@ -402,7 +402,7 @@ Beautifying files
This tool is used to auto-format all HTML and CSS files so that they "look
pretty". The code is auto-indented so that it lines up nicely, blank lines are
inserted where appropriate and so on. Note that beautifying also auto-fixes
broken HTML/CSS. Therefore, if you dont want any auto-fixing to be performed,
broken HTML/CSS. Therefore, if you don't want any auto-fixing to be performed,
first use the Check Book tool to correct all problems and only then run
beautify. Accessed via :guilabel:`Tools->Beautify all files`.
@ -426,7 +426,7 @@ 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
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
generated based on the currently defined Table of Contents.
generated based on the currently defined Table of Contents.
If you use this tool multiple times, each invocation will cause the previously
created inline Table of Contents to be replaced. The tool can be accessed via
@ -459,7 +459,7 @@ Checkpoints
------------------------
:guilabel:`Checkpoints` are a way to mark the current state of the book as "special". You
can then go on to do whatever changes you want to the book and if you dont like
can then go on to do whatever changes you want to the book and if you don't like
the results, return to the checkpointed state. Checkpoints are automatically
created every time you run any of the automated tools described in the
previous section.
@ -525,11 +525,11 @@ While viewing the file you want to split, click the :guilabel:`split mode`
button under the preview panel |spmb|. Then simply move your mouse to the place
where you want to split the file and click. A thick green line will show you
exactly where the split will happen as you move your mouse. Once you have found
the location you want, simply click and the split will be performed.
the location you want, simply click and the split will be performed.
Splitting the file will automatically update all links and references that
pointed into the bottom half of the file and will open the newly split file in
an editor.
an editor.
You can also split a single HTML file at multiple locations automatically, by
right clicking inside the file in the editor and choosing :guilabel:`Split at
@ -537,7 +537,7 @@ multiple locations`. This will allow you to easily split a large file at all
heading tags or all tags having a certain class and so on.
.. raw:: html epub
<div style="clear:both"></div>
The Live CSS panel
@ -565,13 +565,13 @@ with a line through them.
You can enable the Live CSS panel via :guilabel:`View->Live CSS`.
.. raw:: html epub
<div style="clear:both"></div>
Miscellaneous Tools
----------------------
There are a few more tools that can be useful while you edit the book.
There are a few more tools that can be useful while you edit the book.
The Table of Contents View
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -585,7 +585,7 @@ Contents`.
Checking the spelling of words in the book
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can run a spelling checker via :guilabel:`Tools->Check spelling`.
You can run a spelling checker via :guilabel:`Tools->Check spelling`.
.. image:: images/edit-book-spell.png
:alt: The Check Spelling tool
@ -764,7 +764,7 @@ Auto-complete
When editing an ebook, one of the most tedious tasks is creating links to other
files inside the book, or to CSS stylesheets, or images. You have to figure out
the correct filename and relative path to the file. The editor has
auto-complete to make that easier.
auto-complete to make that easier.
As you type a filename, the editor automatically pops up suggestions. Simply
use the Tab key to select the correct file name. The editor even offers
@ -784,10 +784,9 @@ find it saves you a lot of time and effort.
Snippets
^^^^^^^^^^^^^^^
The calibre editor supports *snippets*. A snippet is a
The calibre editor supports *snippets*. A snippet is a
piece of text that is either re-used often or contains a lot of redundant
text. The editor allows you to insert a snippet with only a few key strokes.
The snippets are very powerful, with many features, such as placeholders you
can jump between, automatic mirroring of repeated text and so on.
For more information, see :doc:`snippets`.

69
manual/faq.rst
View File

@ -57,9 +57,9 @@ The first thing to realize is that most ebooks have two tables of contents. One
Then there is the *metadata ToC*. A metadata ToC is a ToC that is not part of the book text and is typically accessed by some special button on a reader. For example, in the calibre viewer, you use the Show Table of Contents button to see this ToC. This ToC cannot be styled by the book creator. How it is represented is up to the viewer program.
In the MOBI format, the situation is a little confused. This is because the MOBI format, alone amongst mainstream ebook formats, *does not* have decent support for a metadata ToC. A MOBI book simulates the presence of a metadata ToC by putting an *extra* content ToC at the end of the book. When you click Goto Table of Contents on your Kindle, it is to this extra content ToC that the Kindle takes you.
In the MOBI format, the situation is a little confused. This is because the MOBI format, alone amongst mainstream ebook formats, *does not* have decent support for a metadata ToC. A MOBI book simulates the presence of a metadata ToC by putting an *extra* content ToC at the end of the book. When you click Goto Table of Contents on your Kindle, it is to this extra content ToC that the Kindle takes you.
Now it might well seem to you that the MOBI book has two identical ToCs. Remember that one is semantically a content ToC and the other is a metadata ToC, even though both might have exactly the same entries and look the same. One can be accessed directly from the Kindle's menus, the other cannot.
Now it might well seem to you that the MOBI book has two identical ToCs. Remember that one is semantically a content ToC and the other is a metadata ToC, even though both might have exactly the same entries and look the same. One can be accessed directly from the Kindle's menus, the other cannot.
When converting to MOBI, calibre detects the *metadata ToC* in the input document and generates an end-of-file ToC in the output MOBI file. You can turn this off by an option in the MOBI Output settings. You can also tell calibre whether to put it and the start or the end of the book via an option in the MOBI Output settings. Remember this ToC is semantically a *metadata ToC*, in any format other than MOBI it *cannot not be part of the text*. The fact that it is part of the text in MOBI is an accident caused by the limitations of MOBI. If you want a ToC at a particular location in your document text, create one by hand. So we strongly recommend that you leave the default as it is, i.e. with the metadata ToC at the end of the book. Also note that if you disable the generation of the end-of-file ToC the resulting MOBI file may not function correctly on a Kindle, since the Kindle's use the metadata ToC for many things, including the Page Flip feature.
@ -83,7 +83,7 @@ to :guilabel:`Preferences->Output Options->MOBI output` and setting the "Enable
of book content" option. If you are reconverting a previously converted book,
you will also have to enable the option in the conversion dialog for that
individual book (as per book conversion settings are saved and take
precedence).
precedence).
Note that doing this will mean that the generated MOBI will show up under
personal documents instead of Books on the Kindle Fire and Amazon whispersync
@ -93,11 +93,11 @@ this bug.
The bug in Amazon's software is that when you put a MOBI file on a Kindle,
unless the file is marked as a Personal document, Amazon assumes you bought the
book from it and tries to download the cover thumbnail for it from its servers. When the
book from it and tries to download the cover thumbnail for it from its servers. When the
download fails, it refuses to fallback to the cover defined in the MOBI file.
This is likely deliberate on Amazon's part to try to force authors to sell only
through them. In other words, Kindle's only display covers for books marked as
Personal Documents or books bought directly from Amazon.
Personal Documents or books bought directly from Amazon.
If you send a MOBI file to an e-ink Kindle with calibre using a USB connection,
calibre works around this Amazon bug by uploading a cover thumbnail itself.
@ -185,7 +185,7 @@ If your device appears as a USB disk to the operating system, adding support for
We just need some information from you:
* 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 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->Miscellaneous`
and click the "Debug device detection" button. This will create some debug output. Copy it to a file
@ -366,7 +366,7 @@ With the USB cable + iTunes
Use 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>`_.
This method only works on Windows Vista and higher, and OS X upto 10.8. Linux
This method only works on Windows Vista and higher, and OS X up to 10.8. 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 to manage books,
replacing it with iBooks.
@ -377,8 +377,8 @@ 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.
The first step to using an Android device is installing an ebook reading
application on it. There are many free and paid ebook reading applications for
Android: Some examples (in no particular order):
`FBReader <https://play.google.com/store/apps/details?id=org.geometerplus.zlibrary.ui.android&hl=en>`_,
Android: Some examples (in no particular order):
`FBReader <https://play.google.com/store/apps/details?id=org.geometerplus.zlibrary.ui.android&hl=en>`_,
`Moon+ <https://play.google.com/store/apps/details?id=com.flyersoft.moonreader&hl=en>`_,
`Mantano <https://play.google.com/store/apps/details?id=com.mantano.reader.android.lite&hl=en>`_,
`Aldiko <https://play.google.com/store/apps/details?id=com.aldiko.android&hl=en>`_,
@ -463,11 +463,11 @@ The most likely cause of this is your antivirus program. Try temporarily disabli
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 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 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 :guilabel:`Preferences->Sharing by Email` in calibre and click the :guilabel:`Use GMX` button and fill in the information asked for.
* calibre will then use GMX to send the mail.
* If you are sending to your Kindle, remember to update the email preferences
@ -479,22 +479,22 @@ Even after doing this, you may have problems. One common source of problems is t
programs block calibre from opening a connection to send email. Try adding an exclusion for calibre in your
antivirus program.
.. note::
.. note::
Microsoft/Google/Gmx can disable your account if you use it to send large
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
risking your account being blocked you can reduce this wait interval by going
to Preferences->Tweaks in calibre.
.. note::
.. note::
Google recently deliberately broke their email sending protocol (SMTP) support in
an attempt to force everyone to use their web interface so they can
show you more ads. They are trying to claim that SMTP is insecure,
that is incorrect and simply an excuse. If you have trouble with
gmail you will need to
gmail you will need to
`allow less secure apps as described here <https://support.google.com/accounts/answer/6010255>`_.
.. note::
.. note::
If you are concerned about giving calibre access to your email
account, simply create a new free email account with GMX or Hotmail
and use it only for calibre.
@ -540,9 +540,9 @@ disconnected from the computer, for the changes to the collections to be
recognized. As such, it is unlikely that any calibre developers will ever feel
motivated enough to support it. There is however, a calibre plugin that allows
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::
Amazon have removed the ability to manipulate collections completely
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.
@ -600,7 +600,7 @@ Metadata about the books is stored in the file ``metadata.db`` at the top level
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 calibre manage author names and sorting?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -610,7 +610,7 @@ Author names are complex, especially across cultures, see `this note <http://www
Now coming to author name sorting:
* 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.
* You can change this algorithm by going to Preferences->Tweaks and setting the :guilabel:`author_sort_copy_method` tweak.
* 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.
@ -626,7 +626,7 @@ With all this flexibility, it is possible to have calibre manage your author nam
* 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.
* Press OK, at which point calibre will change the authors in all your books. This can take a while.
.. note::
When changing from FN LN to LN, FN, it is often the case that the values in author_sort are already in LN, FN format. If this is your case, then do the following:
@ -721,7 +721,7 @@ There can be two reasons why calibre is showing a empty list of books:
and so starts up with an empty library instead. To remedy this, do a
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
calibre library and click OK. If you dont know the new location search your
calibre library and click OK. If you don't know the new location search your
computer for the file :file:`metadata.db`.
* Your metadata.db file was deleted/corrupted. In this case, you can ask
@ -735,7 +735,7 @@ I am getting errors with my calibre library on a networked drive/NAS?
**Do not put your calibre library on a networked drive**.
A filesystem is a complex beast. Most network filesystems lack various
filesystem features that calibre uses. Some dont support file locking, some dont
filesystem features that calibre uses. Some don't support file locking, some don't
support hardlinking, some are just flaky. Additionally, calibre is a single user
application, if you accidentally run two copies of calibre on the same networked
library, bad things will happen. Finally, different OSes impose different
@ -783,10 +783,10 @@ Take your pick:
* A tribute to the SONY Librie which was the first e-ink based ebook reader
* My wife chose it ;-)
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.
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 calibre show only some of my fonts on OS X?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
@ -836,7 +836,7 @@ There are several possible things I know of, that can cause this:
* You recently connected an external monitor or TV to your computer. In
this case, whenever calibre opens a new window like the edit metadata
window or the conversion dialog, it appears on the second monitor where
you dont notice it and so you think calibre has frozen. Disconnect your
you don't notice it and so you think calibre has frozen. Disconnect your
second monitor and restart calibre.
* If you use RoboForm, it is known to cause calibre to crash. Add calibre to
@ -931,7 +931,7 @@ menu, choose "Validate fonts".
I downloaded the installer, but it is not working?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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 rebooting your computer and running a registry cleaner like `Wise registry cleaner <http://www.wisecleaner.com>`_.
@ -941,9 +941,9 @@ Downloading from the Internet can sometimes result in a corrupted download. If t
permissions on your temporary folder are incorrect. Go to the folder
:file:`C:\\Users\\USERNAME\\AppData\\Local` in Windows explorer and then
right click on the :file:`Temp` folder and select :guilabel:`Properties` and go to
the :guilabel:`Security` tab. Make sure that your user account has full control
the :guilabel:`Security` tab. Make sure that your user account has full control
for this folder.
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 calibre is a virus/trojan?
@ -981,15 +981,15 @@ Most purchased EPUB books have `DRM <http://drmfree.calibre-ebook.com/about#drm>
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 calibre.
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.
* If you, or some program you used changed the file permissions of the files in question to read only.
* 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 there is a filesystem error on the device which caused your operating system to mount the filesystem in read only mode or mark a particular file as read only pending recovery.
* If the files have their owner set to a user other than you.
* 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 referred 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 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?
@ -1030,7 +1030,7 @@ For many reasons:
* calibre downloads currently use `about 100TB of bandwidth a month
<http://calibre-ebook.com/dynamic/downloads>`_. Implementing automatic
updates would greatly increase that and end up costing thousands of dollars
a month, which someone has to pay.
a month, which someone has to pay.
* 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
@ -1059,7 +1059,7 @@ How do I run parts of calibre like news download and the content server on my ow
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::
calibre needs GLIBC >= 2.13 and libstdc++ >= 6.0.17. If you have an older
server, you will either need to compile these from source, or use calibre 1.48
which requires only GLIBC >= 2.10. In addition, although the calibre
@ -1090,4 +1090,3 @@ Finally, you can add downloaded news to the calibre library with::
/opt/calibre/calibredb add --with-library /path/to/library outfile.epub
Remember to read the command line documentation section of the calibre User Manual to learn more about these, and other commands.

20
manual/function_mode.rst
View File

@ -4,14 +4,14 @@ Function Mode for Search & Replace in the Editor
The Search & Replace tool in the editor support a *function mode*. In this
mode, you can combine regular expressions (see :doc:`regexp`) with
arbitrarily powerful python functions to do all sorts of advanced text
processing.
processing.
In the standard *regexp* mode for search and replace, you specify both a
regular expression to search for as well as a template that is used to replace
all found matches. In function mode, instead of using a fixed template, you
specify an arbitrary function, in the
specify an arbitrary function, in the
`python programming language <https://docs.python.org/2.7/>`_. This allows
you to do lots of things that are not possible with simple templates.
you to do lots of things that are not possible with simple templates.
Techniques for using function mode and the syntax will be described by means of
examples, showing you how to create functions to perform progressively more
@ -29,7 +29,7 @@ Here, we will leverage one of the builtin functions in the editor to
automatically change the case of all text inside heading tags to title case::
Find expression: <([Hh][1-6])[^>]*>.+?</\1>
For the function, simply choose the :guilabel:`Title-case text (ignore tags)` builtin
function. The will change titles that look like: ``<h1>some TITLE</h1>`` to
``<h1>Some Title</h1>``. It will work even if there are other HTML tags inside
@ -53,7 +53,7 @@ function and copy the python code from below.
return match.group().replace('--', '—').replace('-', '—')
Every Search & Replace custom function must have a unique name and consist of a
python function named replace, that accepts all the arguments shown above.
python function named replace, that accepts all the arguments shown above.
For the moment, we wont worry about all the different arguments to
``replace()`` function. Just focus on the ``match`` argument. It represents a
match when running a search and replace. Its full documentation in available
@ -96,7 +96,7 @@ write a simple function to automatically find and fix such words.
# Search for words split by a hyphen
text = replace_entities(match.group()[1:-1]) # Handle HTML entities like &amp;
corrected = regex.sub(r'(\w+)\s*-\s*(\w+)', replace_word, text, flags=regex.VERSION1 | regex.UNICODE)
return '>%s<' % prepare_string_for_xml(corrected) # Put back required entities
return '>%s<' % prepare_string_for_xml(corrected) # Put back required entities
Use this function with the same find expression as before, namely::
@ -154,7 +154,7 @@ Auto create a Table of Contents
-------------------------------------
Finally, lets try something a little more ambitious. Suppose your book has
headings in ``h1`` and ``h2`` tags that look like
headings in ``h1`` and ``h2`` tags that look like
``<h1 id="someid">Some Text</h1>``. We will auto-generate an HTML Table of
Contents based on these headings. Create the custom function below:
@ -187,7 +187,7 @@ Contents based on these headings. Create the custom function below:
data['toc'] = []
tag_name, anchor, text = match.group(1), replace_entities(match.group(2)), replace_entities(match.group(3))
data['toc'].append((file_name, tag_name, anchor, text))
return match.group() # We dont want to make any actual changes, so return the original matched text
return match.group() # We don't want to make any actual changes, so return the original matched text
# Ensure that we are called once after the last match is found so we can
# output the ToC
@ -225,7 +225,7 @@ The API for the function mode
All function mode functions must be python functions named replace, with the
following signature::
def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs):
return a_string
@ -238,7 +238,7 @@ documented below.
The ``match`` argument
^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``match`` argument represents the currently found match. It is a
The ``match`` argument represents the currently found match. It is a
`python Match object <https://docs.python.org/2.7/library/re.html#match-objects>`_.
It's most useful method is ``group()`` which can be used to get the matched
text corresponding to individual capture groups in the search regular

110
manual/template_lang.rst
View File

@ -21,7 +21,7 @@ The slashes are text, which is put into the template where it appears. For examp
For the book "The Foundation" by "Isaac Asimov" it will become::
Asimov, Isaac Some Important Text The Foundation/The Foundation - Isaac Asimov
You can use all the various metadata fields available in calibre in a template, including any custom columns you have created yourself. To find out the template name for a column simply hover your mouse over the column header. Names for custom fields (columns you have created yourself) always have a # as the first character. For series type custom fields, there is always an additional field named ``#seriesname_index`` that becomes the series index for that series. So if you have a custom series field named ``#myseries``, there will also be a field named ``#myseries_index``.
In addition to the column based fields, you also can use::
@ -62,7 +62,7 @@ Using this syntax, we can solve the above series problem with the template::
The hyphens will be included only if the book has a series index, which it will have only if it has a series.
Notes: you must include the : character if you want to use a prefix or a suffix. You must either use no \| characters or both of them; using one, as in ``{field:| - }``, is not allowed. It is OK not to provide any text for one side or the other, such as in ``{series:|| - }``. Using ``{title:||}`` is the same as using ``{title}``.
Notes: you must include the : character if you want to use a prefix or a suffix. You must either use no \| characters or both of them; using one, as in ``{field:| - }``, is not allowed. It is OK not to provide any text for one side or the other, such as in ``{series:|| - }``. Using ``{title:||}`` is the same as using ``{title}``.
Second: formatting. Suppose you wanted to ensure that the series_index is always formatted as three digits with leading zeros. This would do the trick::
@ -103,7 +103,7 @@ Using functions in templates - single-function mode
Suppose you want to display the value of a field in upper case, when that field is normally in title case. You can do this (and many more things) using the functions available for templates. For example, to display the title in upper case, use ``{title:uppercase()}``. To display it in title case, use ``{title:titlecase()}``.
Function references appear in the format part, going after the ``:`` and before the first ``|`` or the closing ``}``. If you have both a format and a function reference, the function comes after another ``:``. Functions must always end with ``()``. Some functions take extra values (arguments), and these go inside the ``()``.
Function references appear in the format part, going after the ``:`` and before the first ``|`` or the closing ``}``. If you have both a format and a function reference, the function comes after another ``:``. Functions must always end with ``()``. Some functions take extra values (arguments), and these go inside the ``()``.
Functions are always applied before format specifications. See further down for an example of using both a format and a function, where this order is demonstrated.
@ -135,7 +135,7 @@ The functions available are listed below. Note that the definitive documentation
* ``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.
* ``subitems(val, start_index, end_index)`` -- This function is used to break apart lists of tag-like hierarchical items such as genres. It interprets the value as a comma-separated list of tag-like items, where each item is a period-separated list. Returns a new list made by first finding all the period-separated tag-like items, then for each such item extracting the components from `start_index` to `end_index`, then combining the results back together. The first component in a period-separated list has an index of zero. If an index is negative, then it counts from the end of the list. As a special case, an end_index of zero is assumed to be the length of the list. Examples::
Assuming a #genre column containing "A.B.C":
Assuming a #genre column containing "A.B.C":
{#genre:subitems(0,1)} returns "A"
{#genre:subitems(0,2)} returns "A.B"
{#genre:subitems(1,0)} returns "B.C"
@ -144,11 +144,11 @@ The functions available are listed below. Note that the definitive documentation
{#genre:subitems(0,2)} returns "A.B, D.E"
* ``sublist(val, start_index, end_index, separator)`` -- interpret the value as a list of items separated by `separator`, returning a new list made from the items from `start_index`to `end_index`. The first item is number zero. If an index is negative, then it counts from the end of the list. As a special case, an end_index of zero is assumed to be the length of the list. Examples assuming that the tags column (which is comma-separated) contains "A, B ,C"::
{tags:sublist(0,1,\,)} returns "A"
{tags:sublist(-1,0,\,)} returns "C"
{tags:sublist(0,-1,\,)} returns "A, B"
* ``swap_around_comma(val) `` -- given a value of the form ``B, A``, return ``A B``. This is most useful for converting names in LN, FN format to FN LN. If there is no comma, the function returns val unchanged.
* ``switch(pattern, value, pattern, value, ..., else_value)`` -- for each ``pattern, value`` pair, checks if the field matches the regular expression ``pattern`` and if so, returns that ``value``. If no ``pattern`` matches, then ``else_value`` is returned. You can have as many ``pattern, value`` pairs as you want.
* ``test(text if not empty, text if empty)`` -- return `text if not empty` if the field is not empty, otherwise return `text if empty`.
@ -157,17 +157,17 @@ The functions available are listed below. Note that the definitive documentation
Now, what about using functions and formatting in the same field. Suppose you have an integer custom column called ``#myint`` that you want to see with leading zeros, as in ``003``. To do this, you would use a format of ``0>3s``. However, by default, if a number (integer or float) equals zero then the field produces the empty value, so zero values will produce nothing, not ``000``. If you really want to see ``000`` values, then you use both the format string and the ``ifempty`` function to change the empty value back to a zero. The field reference would be::
{#myint:0>3s:ifempty(0)}
Note that you can use the prefix and suffix as well. If you want the number to appear as ``[003]`` or ``[000]``, then use the field::
{#myint:0>3s:ifempty(0)|[|]}
.. _template_mode:
Using functions in templates - template program mode
----------------------------------------------------
The template language program mode differs from single-function mode in that it permits you to write template expressions that refer to other metadata fields, modify values, and do arithmetic. It is a reasonably complete programming language.
The template language program mode differs from single-function mode in that it permits you to write template expressions that refer to other metadata fields, modify values, and do arithmetic. It is a reasonably complete programming language.
You can use the functions documented above in template program mode. See below for details.
@ -182,7 +182,7 @@ The example shows several things:
* functions must be given all their arguments. There is no default value. For example, the standard built-in functions must be given an additional initial parameter indicating the source field, which is a significant difference from single-function mode.
* white space is ignored and can be used anywhere within the expression.
* constant strings are enclosed in matching quotes, either ``'`` or ``"``.
The language is similar to ``functional`` languages in that it is built almost entirely from functions. A statement is a function. An expression is a function. Constants and identifiers can be thought of as functions returning the value indicated by the constant or stored in the identifier.
The syntax of the language is shown by the following grammar::
@ -200,21 +200,21 @@ Comments are lines with a '#' character at the beginning of the line.
An ``expression`` always has a value, either the value of the constant, the value contained in the identifier, or the value returned by a function. The value of a ``statement`` is the value of the last expression in the sequence of statements. As such, the value of the program (statement)::
1; 2; 'foobar'; 3
is 3.
Another example of a complex but rather silly program might help make things clearer::
{series_index:'
substr(
strcat($, '->',
cmp(divide($, 2), 1,
assign(c, 1); substr('lt123', c, 0),
strcat($, '->',
cmp(divide($, 2), 1,
assign(c, 1); substr('lt123', c, 0),
'eq', 'gt')),
0, 6)
'| prefix | suffix}
This program does the following:
This program does the following:
* specify that the field being looked at is series_index. This sets the value of the variable ``$``.
* calls the ``substr`` function, which takes 3 parameters ``(str, start, end)``. It returns a string formed by extracting the start through end characters from string, zero-based (the first character is character zero). In this case the string will be computed by the ``strcat`` function, the start is 0, and the end is 6. In this case it will return the first 6 characters of the string returned by ``strcat``, which must be evaluated before substr can return.
@ -239,8 +239,8 @@ The following functions are available in addition to those described in single-f
* ``add(x, y)`` -- returns x + y. Throws an exception if either x or y are not numbers.
* ``assign(id, val)`` -- assigns val to id, then returns val. id must be an identifier, not an expression
* ``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_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_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
* ``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``.
* ``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()'}``.
@ -250,22 +250,22 @@ The following functions are available in addition to those described in single-f
* ``eval(string)`` -- evaluates the string as a program, passing the local variables (those ``assign`` ed to). This permits using the template processor to construct complex results from local variables. Because the `{` and `}` characters are special, you must use `[[` for the `{` character and `]]` for the '}' character; they are converted automatically. Note also that prefixes and suffixes (the `|prefix|suffix` syntax) cannot be used in the argument to this function when using template program mode.
* ``field(name)`` -- returns the metadata field named by ``name``.
* ``first_matching_cmp(val, cmp1, result1, cmp2, r2, ..., else_result)`` -- compares "val < cmpN" in sequence, returning resultN for the first comparison that succeeds. Returns else_result if no comparison succeeds. Example::
``first_matching_cmp(10,5,"small",10,"middle",15,"large","giant")``
returns "large". The same example with a first value of 16 returns "giant".
* ``first_non_empty(value, value, ...)`` -- returns the first value that is not empty. If all values are empty, then the empty value is returned. You can have as many values as you want.
* ``format_date(x, date_format)`` -- format_date(val, format_string) -- format the value, which must be a date field, using the format_string, returning a string. The formatting codes are::
d : the day as number without a leading zero (1 to 31)
dd : the day as number with a leading zero (01 to 31)
ddd : the abbreviated localized day name (e.g. "Mon" to "Sun").
dddd : the long localized day name (e.g. "Monday" to "Sunday").
M : the month as number without a leading zero (1 to 12).
MM : the month as number with a leading zero (01 to 12)
MMM : the abbreviated localized month name (e.g. "Jan" to "Dec").
MMMM : the long localized month name (e.g. "January" to "December").
yy : the year as two digit number (00 to 99).
dd : the day as number with a leading zero (01 to 31)
ddd : the abbreviated localized day name (e.g. "Mon" to "Sun").
dddd : the long localized day name (e.g. "Monday" to "Sunday").
M : the month as number without a leading zero (1 to 12).
MM : the month as number with a leading zero (01 to 12)
MMM : the abbreviated localized month name (e.g. "Jan" to "Dec").
MMMM : the long localized month name (e.g. "January" to "December").
yy : the year as two digit number (00 to 99).
yyyy : the year as four digit number.
h : the hours without a leading 0 (0 to 11 or 0 to 23, depending on am/pm)
hh : the hours with a leading 0 (00 to 11 or 00 to 23, depending on am/pm)
@ -276,22 +276,22 @@ The following functions are available in addition to those described in single-f
ap : use a 12-hour clock instead of a 24-hour clock, with 'ap' replaced by the localized string for am or pm.
AP : use a 12-hour clock instead of a 24-hour clock, with 'AP' replaced by the localized string for AM or PM.
iso : the date with time and timezone. Must be the only format present.
You might get unexpected results if the date you are formatting contains localized month names, which can happen if you changed the format tweaks to contain MMMM. In this case, instead of using something like ``{pubdate:format_date(yyyy)}``, write the template using template program mode as in ``{:'format_date(raw_field('pubdate'),'yyyy')'}``.
* finish_formatting(val, fmt, prefix, suffix) -- apply the format, prefix, and suffix to a value in the same way as done in a template like ``{series_index:05.2f| - |- }``. This function is provided to ease conversion of complex single-function- or template-program-mode templates to :ref:`general program mode <general_mode>` (see below) to take advantage of GPM template compilation. For example, the following program produces the same output as the above template::
program: finish_formatting(field("series_index"), "05.2f", " - ", " - ")
Another example: for the template ``{series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title}`` use::
program:
program:
strcat(
re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
field('title')
)
* ``formats_modtimes(date_format)`` -- return a comma-separated list of colon_separated items representing modification times for the formats of a book. The date_format parameter specifies how the date is to be formatted. See the date_format function for details. You can use the select function to get the mod time for a specific format. Note that format names are always uppercase, as in EPUB.
* ``formats_paths()`` -- return a comma-separated list of colon_separated items representing full path to the formats of a book. You can use the select function to get the path for a specific format. Note that format names are always uppercase, as in EPUB.
* ``formats_sizes()`` -- return a comma-separated list of colon_separated items representing sizes in bytes of the formats of a book. You can use the select function to get the size for a specific format. Note that format names are always uppercase, as in EPUB.
@ -309,11 +309,11 @@ The following functions are available in addition to those described in single-f
* ``or(value, value, ...)`` -- returns the string "1" if any value is not empty, otherwise returns the empty string. This function works well with test or first_non_empty. You can have as many values as you want.
* ``print(a, b, ...)`` -- prints the arguments to standard output. Unless you start calibre from the command line (``calibre-debug -g``), the output will go to a black hole.
* ``raw_field(name)`` -- returns the metadata field named by name without applying any formatting.
* ``raw_list(name, separator)`` -- returns the metadata list named by name without applying any formatting or sorting and with items separated by separator.
* ``raw_list(name, separator)`` -- returns the metadata list named by name without applying any formatting or sorting and with items separated by separator.
* ``re_group(val, pattern, template_for_group_1, for_group_2, ...)`` -- return a string made by applying the reqular expression pattern to the val and replacing each matched instance with the string computed by replacing each matched group by the value returned by the corresponding template. The original matched value for the group is available as $. In template program mode, like for the template and the eval functions, you use [[ for { and ]] for }. The following example in template program mode looks for series with more than one word and uppercases the first word::
{series:'re_group($, "(\S* )(.*)", "[[$:uppercase()]]", "[[$]]")'}
* ``series_sort()`` -- returns the series sort value.
* ``strcat(a, b, ...)`` -- can take any number of arguments. Returns a string formed by concatenating all the arguments.
* ``strcat_max(max, string1, prefix2, string2, ...)`` -- Returns a string formed by concatenating the arguments. The returned value is initialized to string1. `Prefix, string` pairs are added to the end of the value as long as the resulting string length is less than `max`. String1 is returned even if string1 is longer than max. You can pass as many `prefix, string` pairs as you wish.
@ -325,7 +325,7 @@ The following functions are available in addition to those described in single-f
* ``template(x)`` -- evaluates x as a template. The evaluation is done in its own context, meaning that variables are not shared between the caller and the template evaluation. Because the `{` and `}` characters are special, you must use `[[` for the `{` character and `]]` for the '}' character; they are converted automatically. For example, ``template('[[title_sort]]') will evaluate the template ``{title_sort}`` and return its value. Note also that prefixes and suffixes (the `|prefix|suffix` syntax) cannot be used in the argument to this function when using template program mode.
.. _template_functions_reference:
Function classification
---------------------------
@ -334,7 +334,7 @@ Function classification
generated/|lang|/template_ref
.. _general_mode:
Using general program mode
@ -349,15 +349,15 @@ The following example is a `program:` mode implementation of a recipe on the Mob
The solution requires creating three composite columns. The first column is used to remove the leading articles. The second is used to compute the 'shorten' form. The third is to compute the 'initials' form. Once you have these columns, the plugboard selects between them. You can hide any or all of the three columns on the library view.
First column:
Name: #stripped_series.
Name: #stripped_series.
Template: {series:re(^(A|The|An)\s+,)||}
Second column (the shortened form):
Name: #shortened.
Name: #shortened.
Template: {#stripped_series:shorten(4,-,4)}
Third column (the initials form):
Name: #initials.
Name: #initials.
Template: {#stripped_series:re(([^\s])[^\s]+(\s|$),\1)}
Plugboard expression:
@ -387,7 +387,7 @@ The solution requires creating three composite columns. The first column is used
The following program produces the same results as the original recipe, using only one custom column to hold the results of a program that computes the special title value::
Custom column:
Custom column:
Name: #special_title
Template: (the following with all leading spaces removed)
program:
@ -398,21 +398,21 @@ The following program produces the same results as the original recipe, using on
# Format the series index. Ends up as empty if there is no series index.
# Note that leading and trailing spaces will be removed by the formatter,
# so we cannot add them here. We will do that in the strcat below.
# so we cannot add them here. We will do that in the strcat below.
# Also note that because we are in 'program' mode, we can freely use
# curly brackets in strings, something we cannot do in template mode.
s_index = template('{series_index:0>2.0f}');
# print(stripped, shortened, initials, s_index);
# Now concatenate all the bits together. The switch picks between
# initials and shortened, depending on whether there is a space
# Now concatenate all the bits together. The switch picks between
# initials and shortened, depending on whether there is a space
# in stripped. We then add the brackets around s_index if it is
# not empty. Finally, add the title. As this is the last function in
# the program, its value will be returned.
# the program, its value will be returned.
strcat(
switch( stripped,
'.\s', initials,
switch( stripped,
'.\s', initials,
'.', shortened,
field('series')),
test(s_index, strcat(' [', s_index, '] '), ''),
@ -445,7 +445,7 @@ The lookup function lets us do even fancier processing. For example, assume that
To accomplish this, we:
1. Create a composite field (call it AA) containing ``{series}/{series_index} - {title'}``. If the series is not empty, then this template will produce `series/series_index - title`.
2. Create a composite field (call it BB) containing ``{#genre:ifempty(Unknown)}/{author_sort}/{title}``. This template produces `genre/author_sort/title`, where an empty genre is replaced wuth `Unknown`.
2. Create a composite field (call it BB) containing ``{#genre:ifempty(Unknown)}/{author_sort}/{title}``. This template produces `genre/author_sort/title`, where an empty genre is replaced with `Unknown`.
3. Set the save template to ``{series:lookup(.,AA,BB)}``. This template chooses composite field AA if series is not empty, and composite field BB if series is empty. We therefore have two completely different save paths, depending on whether or not `series` is empty.
Templates and Plugboards
@ -461,12 +461,12 @@ When a plugboard might apply (content server, save to disk, or send to 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 ``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 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.
Plugboards affect the metadata written into the book when it is saved to disk or written to the device. Plugboards do not affect the metadata used by ``save to disk`` and ``send to device`` to create the file names. Instead, file names are constructed using the templates entered on the appropriate preferences window.
Plugboards affect the metadata written into the book when it is saved to disk or written to the device. Plugboards do not affect the metadata used by ``save to disk`` and ``send to device`` to create the file names. Instead, file names are constructed using the templates entered on the appropriate preferences window.
Helpful Tips
------------

2
src/calibre/devices/usbms/deviceconfig.py
View File

@ -63,7 +63,7 @@ class DeviceConfig(object):
c.add_opt('format_map', default=cls.FORMATS,
help=_('Ordered list of formats the device will accept'))
c.add_opt('use_subdirs', default=cls.SUPPORTS_SUB_DIRS_DEFAULT,
help=_('Place files in sub directories if the device supports them'))
help=_('Place files in sub-directories if the device supports them'))
c.add_opt('read_metadata', default=True,
help=_('Read metadata from files on device'))
c.add_opt('use_author_sort', default=False,

2
src/calibre/ebooks/oeb/polish/check/links.py
View File

@ -145,7 +145,7 @@ class Bookmarks(BadLink):
HELP = _(
'This file stores the bookmarks and last opened information from'
' the calibre ebook viewer. You can remove it if you do not'
' need that information, or dont want to share it with'
' need that information, or don\'t want to share it with'
' other people you send this book to.')
INDIVIDUAL_FIX = _('Remove this file')
level = INFO

2
src/calibre/gui2/actions/add.py
View File

@ -63,7 +63,7 @@ class AddAction(InterfaceAction):
'file is the same book in a different format)')).triggered.connect(
self.add_recursive_single)
ma('recursive-multiple', _('Add books from directories, including '
'sub directories (Multiple books per directory, assumes every '
'sub-directories (Multiple books per directory, assumes every '
'ebook file is a different book)')).triggered.connect(
self.add_recursive_multiple)
arm = self.add_archive_menu = self.add_menu.addMenu(_('Add multiple books from archive (ZIP/RAR)'))

4
src/calibre/gui2/device_drivers/configwidget.ui
View File

@ -86,10 +86,10 @@
<item row="2" column="0">
<widget class="QCheckBox" name="opt_use_subdirs">
<property name="toolTip">
<string>If checked, books are placed into sub directories based on their metadata on the device. If unchecked, books are all put into the top level directory.</string>
<string>If checked, books are placed into sub-directories based on their metadata on the device. If unchecked, books are all put into the top level directory.</string>
</property>
<property name="text">
<string>Use sub directories</string>
<string>Use sub-directories</string>
</property>
</widget>
</item>

2
src/calibre/gui2/preferences/look_feel.ui
View File

@ -566,7 +566,7 @@ A value of zero means calculate automatically.</string>
<item row="0" column="0" colspan="5">
<widget class="QLabel" name="label_13">
<property name="text">
<string>There are two kinds of caches that calibre uses to improve performance when rendering covers in the grid view. A disk cache that is kept on your hard disk and stores the cover thumbnails and an in memory cache used to ensure flicker free rendering of covers. For best results, keep the memory cache small and the disk cache large, unless you have a lot of extra RAM in your computer and dont mind it being used by the memory cache.</string>
<string>There are two kinds of caches that calibre uses to improve performance when rendering covers in the grid view. A disk cache that is kept on your hard disk and stores the cover thumbnails and an in memory cache used to ensure flicker free rendering of covers. For best results, keep the memory cache small and the disk cache large, unless you have a lot of extra RAM in your computer and don't mind it being used by the memory cache.</string>
</property>
<property name="wordWrap">
<bool>true</bool>

4
src/calibre/library/server/ajax.py
View File

@ -371,11 +371,11 @@ class AjaxServer(object):
'count': Number of books in this item,
'url': URL to get list of books in this item,
'has_children': If True this item contains sub categories, look
for an entry corresponding to this item in subcategories int he
for an entry corresponding to this item in subcategories in the
main dictionary,
}
:param sort: How to sort the returned items. CHoices are: name, rating,
:param sort: How to sort the returned items. Choices are: name, rating,
popularity
:param sort_order: asc or desc