[docs] revision of the section 'Command Line Engines'

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

docs/admin/engines/command-line-engines.rst

@@ -1,41 +1,64 @@
 .. _engine command:
 
-==============================
+====================
-Fetch results from commandline
+Command Line Engines
-==============================
-
-Previously, with searx you could search over the Internet on other people's
-computers. Now it is possible to fetch results from your local machine without
-connecting to any networks from the same graphical user interface.
-
-.. _command line engines:
-
-Command line engines
 ====================
 
-In :pull-searx:`2128` a new type of engine has been introduced called ``command``.
+.. sidebar:: info
-This engine lets administrators add engines which run arbitrary shell commands
-and show its output on the web UI of searx.
 
-When creating and enabling a ``command`` engine on a public searx instance,
+   - :origin:`command.py <searx/engines/command.py>`
-you must be careful to avoid leaking private data. The easiest solution
+   - :ref:`offline engines`
-is to add tokens to the engine. Thus, only those who have the appropriate token
-can retrieve results from the it.
 
-The engine base is flexible. Only your imagination can limit the power of this engine. (And
+With *command engines* administrators can run engines to integrate arbitrary
-maybe security concerns.) The following options are available:
+shell commands.
 
-* ``command``: A comma separated list of the elements of the command. A special token {{QUERY}} tells searx where to put the search terms of the user. Example: ``['ls', '-l', '-h', '{{QUERY}}']``
+When creating and enabling a ``command`` engine on a public instance, you must
-* ``delimiter``: A dict containing a delimiter char and the "titles" of each element in keys.
+be careful to avoid leaking private data.  The easiest solution is to limit the
-* ``parse_regex``: A dict containing the regular expressions for each result key.
+access by setting ``tokens`` as described in section :ref:`private engines`.
-* ``query_type``: The expected type of user search terms. Possible values: ``path`` and ``enum``. ``path`` checks if the uesr provided path is inside the working directory. If not the query is not executed. ``enum`` is a list of allowed search terms. If the user submits something which is not included in the list, the query returns an error.
-* ``query_enum``: A list containing allowed search terms if ``query_type`` is set to ``enum``.
-* ``working_dir``: The directory where the command has to be executed. Default: ``.``
-* ``result_separator``: The character that separates results. Default: ``\n``
 
+The engine base is flexible.  Only your imagination can limit the power of this
+engine (and maybe security concerns).  The following options are available:
 
-The example engine below can be used to find files with a specific name in the configured
+``command``:
-working directory.
+  A comma separated list of the elements of the command.  A special token
+  ``{{QUERY}}`` tells where to put the search terms of the user. Example:
+
+  .. code:: yaml
+
+     ['ls', '-l', '-h', '{{QUERY}}']
+
+``delimiter``:
+  A mapping containing a delimiter ``char`` and the *titles* of each element in
+  ``keys``.
+
+``parse_regex``:
+  A dict containing the regular expressions for each result key.
+
+``query_type``:
+
+  The expected type of user search terms.  Possible values: ``path`` and
+  ``enum``.
+
+  ``path``:
+    Checks if the user provided path is inside the working directory.  If not,
+    the query is not executed.
+
+  ``enum``:
+    Is a list of allowed search terms.  If the user submits something which is
+    not included in the list, the query returns an error.
+
+``query_enum``:
+  A list containing allowed search terms if ``query_type`` is set to ``enum``.
+
+``working_dir``:
+
+  The directory where the command has to be executed.  Default: ``./``
+
+``result_separator``:
+  The character that separates results. Default: ``\n``
+
+The example engine below can be used to find files with a specific name in the
+configured working directory:
 
 .. code:: yaml
 
@@ -49,16 +72,8 @@ working directory.
         keys: ['line']
 
 
-Next steps
+Acknowledgment
-==========
+==============
 
-In the next milestone, support for local search engines and indexers (e.g. Elasticsearch)
+This development was sponsored by `Search and Discovery Fund
-are going to be added. This way, you will be able to query your own databases/indexers.
+<https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_.
-
-Acknowledgement
-===============
-
-This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ .
-
-.. _Search and Discovery Fund: https://nlnet.nl/discovery
-.. _NLnet Foundation: https://nlnet.nl/

docs/dev/offline_engines.rst

@@ -8,7 +8,7 @@ Offline Engines
 
    - :ref:`demo offline engine`
    - :ref:`sql engines`
-   - :ref:`command line engines`
+   - :ref:`engine command`
    - :origin:`Redis <searx/engines/redis_server.py>`
 
 To extend the functionality of SearxNG, offline engines are going to be