[doc] create "How to search" user documentation

docs/admin/engines/settings.rst

@@ -226,7 +226,7 @@ Communication with search engines.
 -----------------------
 
 A list of the categories that are displayed as tabs in the user interface.
-Categories not listed here can still be searched with the :ref:`search-syntax`.
+Categories not listed here can still be searched with the :ref:`bang syntax`.
 
 .. code-block:: yaml
 

docs/dev/search_api.rst

@@ -29,7 +29,7 @@ Parameters
   passed to any search engine which does not filter its results based on this
   syntax, you might not get the results you wanted.
 
-  See more at :ref:`search-syntax`
+  See more at :ref:`how to search`
 
 ``categories`` : optional
   Comma separated list, specifies the active search categories

docs/user/how-to-search.rst

@@ -5,40 +5,80 @@
 How to search
 =============
 
-.. _search-syntax:
+.. jinja:: searx
 
-Search syntax
+   SearXNG supports {{engines | length}} search engines.
-=============
+   Since searching all of these for every single query would be too
+   slow SearXNG groups its engines into categories.
 
-SearXNG allows you to modify the default categories, engines and search language
+The most important categories are easily accessible as tabs on the
-via the search query.
+search result page (just like with the mainstream search engines).
 
-Prefix ``!``
+Within a category engines can be enabled or disabled from the
-  to set Category/engine
+:guilabel:`Engines` tab in the preferences (you can access the
+preferences via the :guilabel:`Preferences` link in the Oscar theme
+and the :guilabel:`☰` link in the Simple theme). When you search
+in a category only the enabled engines will be searched.
 
-Prefix: ``:``
+Searching multiple categories
-  to set language
+=============================
 
-Abbrevations of the engines and languages are also accepted.  Engine/category
+In the :guilabel:`User Interface` preferences you can
-modifiers are chainable and inclusive (e.g. with :search:`!it !ddg !wp qwer
+disabled :guilabel:`Search on category select` which
-<?q=%21it%20%21ddg%20%21wp%20qwer>` search in IT category **and** duckduckgo
+changes the tabs on the search result pages into checkboxes,
-**and** wikipedia for ``qwer``).
+letting you search multiple engines at once.
+(Note: If you have JavaScript disabled that is already the case.)
 
-See the :search:`/preferences page <preferences>` for the list of engines,
+.. _bang syntax:
-categories and languages.
 
-Examples
+Bang syntax
-========
+-----------
 
-Search in wikipedia for ``qwer``:
+Alternatively you can use our *bang syntax*.
+For example searching for ``cats !images !videos``
+searches all enabled engines in the Images category
+and all enabled engines in the Videos category.
+Note that the order of the bangs does not matter,
+e.g. ``!videos cats !images`` yields the same results.
 
-- :search:`!wp qwer <?q=%21wp%20qwer>` or
+.. TODO: mention bang autocompletion with JavaScript
-- :search:`!wikipedia qwer :search:<?q=%21wikipedia%20qwer>`
 
-Image search:
+Searching specific engines
+==========================
 
-- :search:`!images Cthulhu <?q=%21images%20Cthulhu>`
+Instead of casting a wide net you can also specifically target engines.
+In the engine preferences you can find a "shortcut" for each engine,
+which you can use with the same bang syntax you know from categories.
+For example searching for ``!ddg ducks`` searches for "ducks" only in
+the DuckDuckGo search engine.
 
-Custom language in wikipedia:
+Note that you can combine category bangs with engine bangs, so e.g.
+the query ``!ddg !images ducks`` searches the DuckDuckGo engine along
+with all enabled engines in the images category for "ducks".
+(For engine bangs it does not matter if the engine is enabled or
+disabled within its category, if you ask for an engine explicitly it is
+always searched.)
 
-- :search:`:hu !wp hackerspace <?q=%3Ahu%20%21wp%20hackerspace>`
+Searching in a language
+=======================
+
+In the language select after the search box you can choose which
+language you want your search results to be in. Note that no matter
+what you choose you might still get results in other languages (mostly
+English) because not every engine supports language selection (you can
+see which ones do in the engine preferences).
+
+Alternatively you can use the special syntax ``:es gato`` to search for
+"gato" in Spanish, ``:fr chat`` to search for "chat" in French, ``:de
+katze`` to search for "katze" in German, etc.
+
+.. TODO: how do you find the language code for a language?
+
+Note that unlike the bang syntax the language codes cannot be combined.
+Searching for ``:es :fr cat`` does **not** search for "cat" in Spanish
+and French it only searches in French (the last language code is used).
+
+Also note that searching for ``:es gato`` changes your default search
+language to Spanish so subsequent searches will also be in Spanish
+(until you change the language in the language select or use another
+language code).