From e11b6ef0b3318786caca8f08a184d5cfc55c6211 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Thu, 12 Nov 2020 10:58:30 +0530 Subject: [PATCH] Move URL scheme handler docs into its own document --- manual/gui.rst | 61 --------------------------------------- manual/simple_index.rst | 1 + manual/url_scheme.rst | 64 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 65 insertions(+), 61 deletions(-) create mode 100644 manual/url_scheme.rst diff --git a/manual/gui.rst b/manual/gui.rst index cd687199d8..9d74c62ac1 100644 --- a/manual/gui.rst +++ b/manual/gui.rst @@ -782,64 +782,3 @@ 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. diff --git a/manual/simple_index.rst b/manual/simple_index.rst index 60eec123d2..a71c6519f1 100644 --- a/manual/simple_index.rst +++ b/manual/simple_index.rst @@ -38,6 +38,7 @@ available `_. metadata faq tutorials + url_scheme customize generated/en/cli-index develop diff --git a/manual/url_scheme.rst b/manual/url_scheme.rst new file mode 100644 index 0000000000..809cea18c6 --- /dev/null +++ b/manual/url_scheme.rst @@ -0,0 +1,64 @@ +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. + + +.. contents:: + :depth: 1 + :local: + +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.