[doc] additional descriptions about categories & categories_as_tabs

Add missing documentation of PR [#634].  Related to checkbox "Document how to
categorize engines" in [#690].

Related:

- [#634] https://github.com/searxng/searxng/pull/634#issuecomment-1004757502
- [#690] https://github.com/searxng/searxng/issues/690
- https://github.com/searxng/searxng/issues/1604
- https://github.com/searxng/searxng/pull/1545

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

docs/admin/engines/settings.rst

@@ -311,7 +311,6 @@ Global Settings
 ``results_on_new_tab``:
   Open result links in a new tab by default.
 
-
 .. _settings redis:
 
 ``redis:``
@@ -451,12 +450,15 @@ Communication with search engines.
   see `httpx verification defaults`_.
 
   In addition to ``verify``, SearXNG supports the ``$SSL_CERT_FILE`` (for a file) and
-  ``$SSL_CERT_DIR`` (for a directory) OpenSSL variables.  
+  ``$SSL_CERT_DIR`` (for a directory) OpenSSL variables.
   see `httpx ssl configuration`_.
 
 ``max_redirects`` :
   30 by default. Maximum redirect before it is an error.
 
+
+.. _settings categories_as_tabs:
+
 ``categories_as_tabs:``
 -----------------------
 
@@ -477,6 +479,15 @@ Categories not listed here can still be searched with the :ref:`search-syntax`.
     files:
     social media:
 
+Engines are added to ``categories:`` (compare :ref:`engine categories`), the
+categories listed in ``categories_as_tabs`` are shown as tabs in the UI.  If
+there are no active engines in a category, the tab is not displayed (e.g. if a
+user disables all engines in a category).
+
+On the preferences page (``/preferences``) -- under *engines* -- there is an
+additional tab, called *other*.  In this tab are all engines listed that are not
+in one of the UI tabs (not included in ``categories_as_tabs``).
+
 .. _settings engine:
 
 Engine settings
@@ -552,10 +563,21 @@ engine is shown.  Most of the options have a default value or even are optional.
   to build and send a ``Accept-Language`` header in the request to the origin
   search engine.
 
+.. _engine categories:
+
 ``categories`` : optional
-  Define in which categories this engine will be active.  Most of the time, it is
+  Specifies to which categories the engine should be added.  Engines can be
-  defined in the code of the engine, but in a few cases it is useful, like when
+  assigned to multiple categories.
-  describing multiple search engine using the same code.
+
+  Categories can be shown as tabs (:ref:`settings categories_as_tabs`) in the
+  UI.  A search in a tab (in the UI) will query all engines that are active in
+  this tab.  In the preferences page (``/preferences``) -- under *engines* --
+  users can select what engine should be active when querying in this tab.
+
+  Alternatively, :ref:`\!bang <search-syntax>` can be used to search all engines
+  in a category, regardless of whether they are active or not, or whether they
+  are in a tab of the UI or not.  For example, ``!dictionaries`` can be used to
+  query all search engines in that category (group).
 
 ``timeout`` : optional
   Timeout of the search with the current search engine.  **Be careful, it will
@@ -658,7 +680,7 @@ and can relied on the default configuration :origin:`searx/settings.yml` using:
 ``engines:``
   With ``use_default_settings: true``, each settings can be override in a
   similar way, the ``engines`` section is merged according to the engine
-  ``name``.  In this example, SearXNG will load all the default engines, will 
+  ``name``.  In this example, SearXNG will load all the default engines, will
   enable the ``bing`` engine and define a :ref:`token <private engines>` for
   the arch linux engine:
 

docs/dev/engine_overview.rst

@@ -46,7 +46,7 @@ Engine File
    ======================= =========== ========================================================
    argument                type        information
    ======================= =========== ========================================================
-   categories              list        pages, in which the engine is working
+   categories              list        categories, in which the engine is working
    paging                  boolean     support multiple pages
    time_range_support      boolean     support search time range
    engine_type             str         - ``online`` :ref:`[ref] <demo online engine>` by

searx/enginelib/__init__.py

@@ -81,7 +81,7 @@ class Engine:  # pylint: disable=too-few-public-methods
     # settings.yml
 
     categories: List[str]
-    """Tabs, in which the engine is working."""
+    """Specifies to which :ref:`engine categories` the engine should be added."""
 
     name: str
     """Name that will be used across SearXNG to define this engine.  In settings, on