[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>

1 files changed, 28 insertions, 6 deletions

diff --git a/docs/admin/engines/settings.rst b/docs/admin/engines/settings.rst
index 0d9e14e57..fa61f6212 100644
--- a/docs/admin/engines/settings.rst
+++ b/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
-  defined in the code of the engine, but in a few cases it is useful, like when
-  describing multiple search engine using the same code.
+  Specifies to which categories the engine should be added.  Engines can be
+  assigned to multiple categories.
+
+  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: