Add documentation for the calibre:// URL scheme

manual/gui.rst

@@ -782,3 +782,64 @@ calibre has several keyboard shortcuts to save you time and mouse movement. Thes
       - Re-apply the current sort
     * - :kbd:`Ctrl+Q`
       - Quit calibre
+
+The calibre:// URL scheme
+------------------------------
+
+calibre registers itself as the handler program for calibre:// URLs. So you can
+use these to perform actions like opening books, searching for books, etc from
+other programs/documents or via the command line. For example, running the
+following at the command line::
+
+    calibre calibre://switch-library/Some_Library
+
+Will open calibre with the library named ``Some Library``. Library names are
+the folder name of the library folder with spaces replaced by underscores. The
+special value ``_`` means the current library.
+The various types of URLs are documented below.
+
+
+Switch to a specific library
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The URL syntax is::
+
+    calibre://switch-library/Library_Name
+
+Library names are the folder name of the library with spaces replaced by
+underscores. The special value ``_`` means the current library. You can also
+use hex encoding for the library names, useful if the library names have
+special characters that would otherwise require URL encoding. Hex encoded
+library names look like::
+
+    _hex_-AD23F4BC
+
+Where the part after the ``_hex_-`` prefix is the library name encoded as UTF-8
+and every byte represented by two hexadecimal characters.
+
+
+Show a specific book in calibre
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The URL syntax is::
+
+    calibre://show-book/Library_Name/book_id
+
+This will show the book with ``book_id`` (a number) in calibre. The ids for
+books can be seen in the calibre interface by hovering over the
+:guilabel:`Click to open` link in the book details panel, it is the number in
+brackets at the end of the path to the book folder.
+
+
+Open a specific book in the viewer at a specific position
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The URL syntax is::
+
+    calibre://view-book/Library_Name/book_id/book_format?open_at=location
+
+Here, ``book_format`` is the format of the book, for example, ``EPUB`` or
+``MOBI`` and the ``location`` is an optional location inside the book. The
+easiest way to get these links is to open a book in the viewer, then in the
+viewer controls select :guilabel:`Go to->Location` and there such a link
+will be given that you can copy/paste elsewhere.

manual/viewer.rst

@@ -79,6 +79,10 @@ books when discussing it with friends or referring to it in other works. You
 can enter these locations under :guilabel:`Go to->Location` in the viewer
 controls.
 
+There is a URL you can copy to the clipboard and paste into other programs
+or documents. Clicking on this URL will open the book in the calibre viewer at
+the current location.
+
 If you click on links inside the e-book to take you to different parts of the
 book, such as an endnote, you can use the :guilabel:`Back` and
 :guilabel:`Forward` buttons in the top left corner of the viewer controls.

src/calibre/gui2/main.py

@@ -40,10 +40,18 @@ class AbortInit(Exception):
 
 def option_parser():
     parser = _option_parser(_('''\
-%prog [options] [path_to_ebook]
+%prog [options] [path_to_ebook or calibre url ...]
 
 Launch the main calibre Graphical User Interface and optionally add the e-book at
-path_to_ebook to the database.
+path_to_ebook to the database. You can also specify calibre URLs to perform various
+different actions, than just adding books. For example:
+
+calibre://view-book/test_library/1842/epub
+
+Will open the book with id 1842 in the EPUB format from the library
+"test_library" in the calibre viewer. Library names are the folder names of the
+libraries with spaces replaced by underscores. A full description of the
+various URL based actions is in the User Manual.
 '''))
     parser.add_option('--with-library', default=None, action='store',
                       help=_('Use the library located at the specified path.'))