From 8ea12b2ce5e1aad6474111f43ae60d2666cc93ae Mon Sep 17 00:00:00 2001 From: Veloman Yunkan Date: Wed, 6 Mar 2024 19:25:25 +0400 Subject: [PATCH 1/5] Fixed the "book name"-vs-"ZIM name" bug in docs --- docs/kiwix-serve.rst | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/kiwix-serve.rst b/docs/kiwix-serve.rst index e38ab809..45eb20a1 100644 --- a/docs/kiwix-serve.rst +++ b/docs/kiwix-serve.rst @@ -339,8 +339,8 @@ filtering criteria must be specified via the following URL parameters: * ``q`` - include in the results only entries that contain the specified text in the title or description. -* ``name`` - include in the results only the entry with the specified - :term:`name `. +* ``name`` - include in the results only entries with a matching + :term:`book name `. Examples: @@ -617,9 +617,11 @@ A multi-ZIM search request must comply with the following constraints: a multi-ZIM search, however must respect the :ref:`multi-ZIM search constraints `. - ``books.name``: :term:`name ` of the ZIM file. Can be repeated - for a multi-ZIM search, however must respect the :ref:`multi-ZIM search - constraints `. + ``books.name``: :term:`name of the ZIM file ` (not to be confused + with ``books.filter.name`` which selects/filters based on the :term:`book + name `). Can be repeated for a multi-ZIM search, however must + respect the :ref:`multi-ZIM search constraints + `. ``books.filter.{criteria}``: allows to take full advantage of :ref:`library filtering ` functionality of the `/catalog/v2/entries`_ @@ -799,6 +801,13 @@ Glossary .. glossary:: + Book name + + Name of the book as specified in the ZIM file metadata (for a + ``kiwix-serve`` started *WITHOUT* the :option:`--library` option) or the + library XML file (for a ``kiwix-serve`` started with the + :option:`--library` option). + ZIM filename Name of a ZIM file on the server filesystem. @@ -808,15 +817,16 @@ Glossary Identifier of a ZIM file in the server's library (used for referring to a particular ZIM file in requests). - For a ``kiwix-serve`` started with a list of ZIM files, ZIM names are - derived from the filename by dropping the extension and replacing certain - characters (spaces are replaced with underscores, and ``+`` symbols are - replaced with the text ``plus``). Presence of the - :option:`-z`/:option:`--nodatealiases` option will create additional names - (aliases) for filenames with dates. + ZIM names are derived from the filenames as follows: + + - file extension is removed, + - all characters are converted to lowercase, + - diacritics are removed, + - spaces are replaced with underscores, + - ``+`` symbols are replaced with the text ``plus``. - For a ``kiwix-serve`` started with the :option:`--library` option, ZIM - names come from the library XML file. + Presence of the :option:`-z`/:option:`--nodatealiases` option will create + additional names (aliases) for filenames with dates. ZIM names are expected to be unique across the library. Any name conflicts (including those caused by the usage of the From dd14e02741b9d6e1e12a5c542d8a3d9aa8480e35 Mon Sep 17 00:00:00 2001 From: Veloman Yunkan Date: Wed, 6 Mar 2024 19:29:44 +0400 Subject: [PATCH 2/5] Documented a couple of /search API's caveats --- docs/kiwix-serve.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/kiwix-serve.rst b/docs/kiwix-serve.rst index 45eb20a1..24dbad89 100644 --- a/docs/kiwix-serve.rst +++ b/docs/kiwix-serve.rst @@ -617,12 +617,24 @@ A multi-ZIM search request must comply with the following constraints: a multi-ZIM search, however must respect the :ref:`multi-ZIM search constraints `. + .. note:: + + If any of the provided ``books.id`` values refers to a book missing + from the library then an error is returned instead of running the + search on the remaining (valid) entries. + ``books.name``: :term:`name of the ZIM file ` (not to be confused with ``books.filter.name`` which selects/filters based on the :term:`book name `). Can be repeated for a multi-ZIM search, however must respect the :ref:`multi-ZIM search constraints `. + .. note:: + + If any of the provided ``books.name`` values refers to a book missing + from the library then an error is returned instead of running the + search on the remaining (valid) entries. + ``books.filter.{criteria}``: allows to take full advantage of :ref:`library filtering ` functionality of the `/catalog/v2/entries`_ endpoint (``{criteria}`` must be replaced with an attribute/filtering From 433010a900f51bf6c16f945c4b2496236f4ad489 Mon Sep 17 00:00:00 2001 From: Veloman Yunkan Date: Wed, 6 Mar 2024 19:56:30 +0400 Subject: [PATCH 3/5] Clarified handling of naming conflicts --- docs/kiwix-serve.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/kiwix-serve.rst b/docs/kiwix-serve.rst index 24dbad89..553fb0e2 100644 --- a/docs/kiwix-serve.rst +++ b/docs/kiwix-serve.rst @@ -820,6 +820,14 @@ Glossary library XML file (for a ``kiwix-serve`` started with the :option:`--library` option). + .. note:: + + Two or more books may have the same name in the library. That's not + considered a conflict, because there may be multiple versions of the + "same" book (differing by the settings of the scraper, date, etc). + :ref:`Library filtering ` by name will return all + matching books. + ZIM filename Name of a ZIM file on the server filesystem. @@ -843,7 +851,8 @@ Glossary ZIM names are expected to be unique across the library. Any name conflicts (including those caused by the usage of the :option:`-z`/:option:`--nodatealiases` option) are reported on STDERR but, - otherwise, are ignored. + otherwise, are ignored (i.e. only one of the entries can be accessed via + the conflicting name). ZIM title From be89de2bbe31b41ad7ba97064145e54029b71184 Mon Sep 17 00:00:00 2001 From: Veloman Yunkan Date: Wed, 6 Mar 2024 20:00:08 +0400 Subject: [PATCH 4/5] More conspicuous "ZIM name" links --- docs/kiwix-serve.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/kiwix-serve.rst b/docs/kiwix-serve.rst index 553fb0e2..7089e2f8 100644 --- a/docs/kiwix-serve.rst +++ b/docs/kiwix-serve.rst @@ -532,7 +532,7 @@ specified ZIM file. **Parameters:** - ``content``: :term:`name ` of the ZIM file. + ``content``: :term:`name of the ZIM file `. .. _raw: @@ -609,7 +609,7 @@ A multi-ZIM search request must comply with the following constraints: below list take precedence over subsequent ones (the later ones, even if present in the request, are simply ignored). - ``content``: :term:`name ` of the ZIM file (for a single-ZIM + ``content``: :term:`name of the ZIM file ` (for a single-ZIM search). This is a :ref:`legacy parameter `. ``books.name`` should be used instead. @@ -753,7 +753,7 @@ added as an option to perform a full text search in the said ZIM file. **Parameters:** - ``content`` (mandatory): :term:`name ` of the ZIM file. + ``content`` (mandatory): :term:`name of the ZIM file `. ``term`` (optional; defaults to an empty string): query text. From 21a145d999f948be763a7fbc1a8e0e7c624a1ad7 Mon Sep 17 00:00:00 2001 From: Veloman Yunkan Date: Wed, 6 Mar 2024 20:23:09 +0400 Subject: [PATCH 5/5] Fixed the copyright date --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index bb815508..6ddfe76c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,7 +18,7 @@ # -- Project information ----------------------------------------------------- project = 'kiwix-tools' -copyright = '2022, kiwix-team' +copyright = '2024, kiwix-team' author = 'kiwix-team'