diff --git a/docs/kiwix-serve.rst b/docs/kiwix-serve.rst index e38ab80..45eb20a 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: - For a ``kiwix-serve`` started with the :option:`--library` option, ZIM - names come from the library XML file. + - 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``. + + 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