diff --git a/manual/creating_plugins.rst b/manual/creating_plugins.rst index e2e928b92e..0b16280417 100644 --- a/manual/creating_plugins.rst +++ b/manual/creating_plugins.rst @@ -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 `_. +You can download the Hello World plugin from +`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 `_ @@ -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 `_. +`editor_demo_plugin.zip `_. The first step, as for all plugins is to create the import name empty txt file, as described :ref:`above `. -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 `_ 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`. diff --git a/manual/edit.rst b/manual/edit.rst index b397037878..295746d9f5 100644 --- a/manual/edit.rst +++ b/manual/edit.rst @@ -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 `_ 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 tags for those stylesheets into all the selected HTML files. .. raw:: html epub - +
@@ -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