Fix small issues in box.execute() (#3498)

Author: andreyaksenov

doc/reference/reference_lua/box_sql/execute.rst

@@ -6,7 +6,7 @@ box.execute()
 
 .. function:: box.execute(sql-statement[, extra-parameters])
 
-    Execute the SQL statement contained in the sql-statement parameter.
+    Execute the SQL statement contained in the ``sql-statement`` parameter.
 
     :param string sql-statement: statement, which should conform to
                                  :ref:`the rules for SQL grammar <sql_statements_and_clauses>`
@@ -16,43 +16,61 @@ box.execute()
 
     .. _box-sql_extra_parameters:
 
-    There are two ways to pass extra parameters for ``box.execute()``:
+    There are two ways to pass extra parameters to ``box.execute()``:
 
     * The first way, which is the preferred way, is to put placeholders in the
-      string, and pass a second argument, an *extra-parameters* table. A
+      string, and pass a second argument, an ``extra-parameters`` table. A
       placeholder is either a question mark "?", or a colon ":" followed by a
       name. An extra parameter is any Lua expression.
-      If placeholders are question marks, then they will be replaced by
-      extra-parameter values in corresponding positions, that is, the first ?
-      will be replaced by the first extra parameter, the second ? will be
-      replaced by the second extra parameter, and so on. If placeholders are
-      :names, then they will be replaced by extra-parameter values with
-      corresponding names. For example this request which contains literal
-      values 1 and 'x': |br|
-      ``box.execute([[INSERT INTO tt VALUES (1, 'x');]]);`` |br|
-      is the same as this request which contains two question-mark placeholders
-      (``?`` and ``?``) and a two-element extra-parameters table: |br|
-      ``x = {1,'x'}`` |br|
-      ``box.execute([[INSERT INTO tt VALUES (?, ?);]], x);`` |br|
-      and is the same as this request which contains two :name placeholders
-      (``:a`` and ``:b``) and a two-element extra-parameters table with elements
-      named "a" and "b": |br|
-      ``box.execute([[INSERT INTO tt VALUES (:a, :b);]], {{[':a']=1},{[':b']='x'}})`` |br|
+
+      If placeholders are question marks, then they are replaced by
+      extra-parameter values in corresponding positions. That is, the first ``?``
+      is replaced by the first extra parameter, the second ``?`` is
+      replaced by the second extra parameter, and so on.
+
+      If placeholders are ``:names``, then they are replaced by ``extra-parameter`` values with
+      corresponding names.
+
+      For example, this request that contains literal values ``1`` and ``'x'``:
+
+      .. code-block:: lua
+
+          box.execute([[INSERT INTO tt VALUES (1, 'x');]]);
+
+      ... is the same as the request below containing two question-mark placeholders
+      (``?`` and ``?``) and a two-element ``extra-parameters`` table:
+
+      .. code-block:: lua
+
+          x = {1,'x'}
+          box.execute([[INSERT INTO tt VALUES (?, ?);]], x);
+
+      ... and is the same as this request containing two ``:name`` placeholders
+      (``:a`` and ``:b``) and a two-element ``extra-parameters`` table with elements
+      named "a" and "b":
+
+      .. code-block:: lua
+
+          box.execute([[INSERT INTO tt VALUES (:a, :b);]], {{[':a']=1},{[':b']='x'}})
+
 
     * The second way is to concatenate strings.
-      For example, this Lua script will insert 10 rows with different primary-key
-      values into table t: |br|
-      ``for i=1,10,1 do`` |br|
-      |nbsp| |nbsp| ``box.execute("insert into t values (" .. i .. ")")`` |br|
-      ``end`` |br|
+      For example, the Lua script below inserts 10 rows with different primary-key
+      values into table ``t``:
+
+      .. code-block:: lua
+
+          for i=1,10,1 do
+              box.execute("insert into t values (" .. i .. ")")
+          end
+
       When creating SQL statements based on user input, application developers
       should beware of `SQL injection <https://en.wikipedia.org/wiki/SQL_injection>`_.
 
     Since ``box.execute()`` is an invocation of a Lua function,
     it either causes an error message or returns a value.
 
-    For some statements the returned value will contain a field named "rowcount".
-    For example;
+    For some statements the returned value contains a field named ``rowcount``, for example:
 
     .. code-block:: tarantoolsession
 
@@ -66,18 +84,18 @@ box.execute()
         ...
 
     For statements that cause generation of values for PRIMARY KEY AUTOINCREMENT columns,
-    there will also be a field named "autoincrement_ids".
+    there is a field named ``autoincrement_id``.
 
     .. _box-sql_result_sets:
 
-    For SELECT or PRAGMA statements, the returned value will be a *result set*,
-    containing a field named "metadata" (a table with column names and
+    For SELECT or PRAGMA statements, the returned value is a *result set*,
+    containing a field named ``metadata`` (a table with column names and
     Tarantool/NoSQL type names)
-    and a field named "rows" (a table with the contents of each row).
+    and a field named ``rows`` (a table with the contents of each row).
 
     For example, for a statement ``SELECT "x" FROM t WHERE "x"=5;``
     where ``"x"`` is an INTEGER column and there is one row,
-    a display on the Tarantool client will look like this:
+    a display on the Tarantool client might look like this:
 
     .. code-block:: tarantoolsession
 
@@ -113,13 +131,13 @@ box.execute()
       :ref:`PRIMARY KEY AUTOINCREMENT <sql_table_constraint_def>`,
       otherwise false.
     * ``span`` (always present) = the original expression in a select list,
-      which will often be the same as ``name`` if the select list specifies a
-      column name and nothing else, but otherwise will differ, for example after
+      which often is the same as ``name`` if the select list specifies a
+      column name and nothing else, but otherwise differs, for example, after
       ``SELECT x+55 AS x FROM t;`` the ``name`` is X and the ``span`` is x+55.
       If ``span`` and ``name`` are the same then the content is MP_NIL.
 
     Alternative: if you are using the Tarantool server as a client,
-    you can switch languages thus:
+    you can switch languages as follows:
 
     .. code-block:: none
 
@@ -129,7 +147,6 @@ box.execute()
     Afterwards, you can enter any SQL statement directly without needing
     ``box.execute()``.
 
-    There is also an ``execute()`` function available via
-    :ref:`module net.box <net_box-module>`, for example after
-    ``conn = net_box.connect(url-string)`` one can say
-    ``conn:execute(sql-statement])``.
+    There is also an ``execute()`` function available in
+    :ref:`module net.box <net_box-module>`.
+    For example, you can execute ``conn:execute(sql-statement])`` after ``conn = net_box.connect(url-string)``.