Apply documentation edits suggested by Peter Gulutzan.

Apply documentation edits suggested by Peter Gulutzan.
Fix 'relink' target to correctlly build target.db.

doc/sql.txt

 ;  
 ; Tarantool SQL parser is implemented entirely on the client side.
 ; This BNF provides a reference of the supported subset of 
-; the standard SQL, to which all clients are strongly encouraged 
+; SQL, to which all clients are strongly encouraged
 ; to stick.
 ; 
 ; Convention: UPPERCASE letters are used for terminals and literals.
 ; Lowercase letters are used for <non-terminals>. SQL is
-; case-insensitive, so this convention is present only to imporve
+; case-insensitive, so this convention is present only to improve
 ; legibility of the BNF.
 
 <sql> ::= <insert> | <replace> | <update> | <delete> | <select>
 
 <insert> ::= INSERT [INTO] <ident> VALUES <value_list>
 
-<insert> ::= REPLACE [INTO] <ident> VALUES <value_list>
+<replace> ::= REPLACE [INTO] <ident> VALUES <value_list>
 
 <update> ::= UPDATE <ident> SET <update_list> <simple_where>
 

doc/user/CMakeLists.txt

@@ -63,11 +63,10 @@ add_custom_target(pdf
     COMMAND fop tarantool_user_guide.fo tarantool_user_guide.pdf)
 
 add_custom_target(relink
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
     COMMAND ${XSLTPROC} --nonet
         --stringparam collect.xref.targets "only"
-        --xinclude -o ${PATH_USERGUIDE_HTML}
-        ${CMAKE_SOURCE_DIR}/doc/user/tnt-html.xsl
-        ${CMAKE_SOURCE_DIR}/doc/user/user.xml)
+        --xinclude tnt-html.xsl user.xml)
 
 #
 # Java saxon-based documentation generation (misc)

doc/user/language-reference.xml

@@ -74,7 +74,7 @@
     header, allows simplifying client or proxy I/O.
     The server response to a request always carries in its header
     the same request type and id.
-    The id makes it possible to always match request to a
+    The id makes it possible to always match a request to a
     response, even if the latter arrived out of order.
   </para>
   <para>Request type defines the format of the payload.
@@ -85,11 +85,11 @@
     exception, all commands operate on whole tuple(s).
   </para>
   <para>Unless implementing a client driver, one needn't
-    concern him or her self with the complications of the binary
+    concern oneself with the complications of the binary
     protocol. <olink targetptr="connectors">Language-specific
     drivers</olink> provide a friendly way to store domain
     language data structures in Tarantool, and the command line
-    client supports a subset of the standard SQL.
+    client supports a subset of standard SQL.
     A complete description of both, the binary protocol and
     the supported SQL, is maintained in annotated Backus-Naur
     form in the source tree: please see
@@ -132,7 +132,7 @@
     understands all administrative statements
     and automatically directs them to the administrative port.
     The server response to an administrative command, even though
-    is always in plain text, can be quite complex.
+    it is always in plain text, can be quite complex.
     It is encoded using YAML markup to simplify automated parsing.
   </para>
   <para>To learn about all supported administrative commands, you
@@ -151,8 +151,8 @@
         <filename><olink
         targetptr="snap_dir"/>/&lt;latest-lsn&gt;.snap</filename>.
         To take a snapshot, Tarantool forks and quickly
-        <function>munmap(2)</function>s all memory except one that
-        stores tuples. Since all modern operating systems support
+        <function>munmap(2)</function>s all memory except memory
+        where tuples are stored. Since all modern operating systems support
         virtual memory copy-on-write, this effectively creates a
         consistent snapshot of all tuples in the child process,
         which is then written to disk tuple by tuple. Since a
@@ -170,7 +170,7 @@
 <programlisting>localhost> show info
 ---
 info:
-  version: "1.4.4"
+  version: "1.4.6"
   lsn: 843301
 ...
 localhost> save snapshot
@@ -258,6 +258,8 @@ info:
         <emphasis role="tntadmin">show stat</emphasis>
       </term>
       <listitem><para>
+      Show the average number of requests per second, and the total number of requests since startup,
+      broken down by request type: INSERT or SELECT or UPDATE or DELETE."
 <programlisting>
 localhost> show stat
 ---
@@ -301,7 +303,7 @@ statistics:
       </term>
       <listitem><para>
         A pool allocator is used for temporary memory, when
-        serving client requests. Every fiber has an own
+        serving client requests. Every fiber has its own
         pool. Shows the current state of pools of all fibers.
       </para></listitem>
     </varlistentry>
@@ -334,7 +336,7 @@ statistics:
       <listitem><para>
         Execute a chunk of Lua code. This can be used to define,
         invoke, debug and drop <olink
-        targetptr="stored-programs">stored programs</olink>,
+        targetptr="stored-procedures">stored procedures</olink>,
         inspect server environment, perform automated
         administrative tasks.
       </para></listitem>
@@ -344,7 +346,7 @@ statistics:
 
 </section>
 
-<xi:include href="stored-programs.xml" />
+<xi:include href="stored-procedures.xml" />
 
 </chapter>
 

doc/user/stored-programs.xml → doc/user/stored-procedures.xml

@@ -5,7 +5,7 @@
 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
       xmlns:xi="http://www.w3.org/2001/XInclude"
       xmlns:xlink="http://www.w3.org/1999/xlink"
-      xml:id="stored-programs">
+      xml:id="stored-procedures">
   <title>Writing stored procedures in Lua</title>
 <blockquote>
     <para>
@@ -33,7 +33,7 @@ Found 1 tuple:
     In the language of the administrative console
     <olink targetptr="lua-command" /> evaluates an arbitrary
     Lua chunk. CALL is the SQL standard statement used
-    to represent CALL command of the binary
+    to invoke the CALL command of the binary
     protocol.
     In the example above, a Lua procedure is first defined
     using the text protocol of the administrative port,
@@ -95,7 +95,7 @@ expirationd.run_task("exprd space 0", 0, is_expired, nil,
   </para>
 
   <para>
-    There is a single global instance of Lua interpreter, which is
+    There is a single global instance of the Lua interpreter, which is
     shared across all connections. Anything prefixed with
     <code>lua </code> on the administrative console is sent
     directly to this interpreter. Any change of the interpreter
@@ -103,7 +103,7 @@ expirationd.run_task("exprd space 0", 0, is_expired, nil,
   </para>
   <para>
     Each connection, however, is using its own Lua
-    <emphasis>coroutine</emphasis> &mdash; a mechanism, akin to
+    <emphasis>coroutine</emphasis> &mdash; a mechanism akin to
     Tarantool <emphasis>fibers</emphasis>. A coroutine has an
     own execution stack and a Lua <emphasis>closure</emphasis>
     &mdash; set of local variables and definitions.
@@ -180,7 +180,7 @@ error: 1:15 expected '('
     When a function in Lua terminates with an error, the error
     is sent to the client as <olink targetptr="ER_PROC_LUA" />
     return code, with the original error message preserved.
-    Similarly, an error occurred inside Tarantool (observed on the
+    Similarly, an error which has occurred inside Tarantool (observed on the
     client as an error code), when happens during execution of a
     Lua procedure, produces a genuine Lua error:
 <programlisting><computeroutput>localhost> lua function f1() error("oops") end
@@ -247,7 +247,7 @@ pack: function
             <para>
                 Process a request passed in as a binary string.
                 This is an entry point into the server request
-                processor. It allows to insert, update,
+                processor. It can be used to insert, update,
                 select and delete tuples from within a Lua procedure.
             </para>
             <para>
@@ -373,8 +373,8 @@ localhost> lua box.select(5, 1, 'firstname', 'lastname')
                 single character of format describes either an
                 operation which needs to take place or operation
                 argument. A format specifier also works as a
-                placeholder for the number of field, which needs
-                to be updated, or argument value.
+                placeholder for the number of a field, which needs
+                to be updated, or for an argument value.
                 For example: 
                 <simplelist>
                     <member><code>+p=p</code> &mdash; add a value
@@ -419,7 +419,7 @@ localhost> lua box.update(0, 2, '!p', 1, 'Bienvenue tout le monde!')
 ---
  - 2: {'Bienvenue tout le monde!', 'Hello world!'}
 ...
-localhost> lua box.update(0, 2, '#p', 2, 'Biennvenue tout le monde!')
+localhost> lua box.update(0, 2, '#p', 2, 'Bienvenue tout le monde!')
 ---
  - 2: {'Bienvenue tout le monde!'}
 ...
@@ -467,7 +467,7 @@ Call ERROR, Illegal parameters, key is not u32 (ER_ILLEGAL_PARAMS)
             can change significantly if data is inserted or deleted
             between two calls to <code>box.select_range()</code>.
             If <code>key</code> is <code>nil</code> or unspecified,
-            the selection starts from start of the index.
+            the selection starts from the start of the index.
             <bridgehead renderas="sect4">Example</bridgehead>
 <programlisting>localhost> show configuration
 ---
@@ -535,8 +535,8 @@ localhost> lua box.select_range(4, 1, 2, '1')
                 string, low byte first,
                 </member>
                 <member><code>p</code> &mdash; stores the length
-                of the argument as a 4-byte int, low byte first,
-                followed by the argument itself: a 4-byte int, low
+                of the argument as a 4-byte integer, low byte first,
+                followed by the argument itself: a 4-byte integer, low
                 byte first, for integers, or a binary blob for
                 anything else,
                 </member>
@@ -732,8 +732,8 @@ localhost> lua t:slice(1, -1)
         </term>
         <listitem><simpara>
             A container for all defined indexes. An index is a Lua object
-            of type <code xlink:href="#box.index">box.index</code> which
-            allows to search tuples and iterate over them in predefined order.
+            of type <code xlink:href="#box.index">box.index</code> with
+            methods to search tuples and iterate over them in predefined order.
         </simpara></listitem>
     </varlistentry>
     <varlistentry>
@@ -992,18 +992,21 @@ localhost> lua for k,v in i.next, i, nil do print(v) end
 
 <variablelist>
     <title>Package <code>box.fiber</code></title>
-    <para>Functions in this package allow to create, run and
+    <para>Functions in this package allow you to create, run and
     manage existing <emphasis>fibers</emphasis>.
     </para>
     <para>
 A fiber is an independent execution thread implemented
 using a mechanism of cooperative multitasking.
-Each fiber can be running, suspended or dead.
-A fiber is created (<code>box.fiber.create()</code>) suspended.
-It can be started with <code>box.fiber.resume()</code>, yield
-control back to the caller with <code>box.fiber.yield()</code>
-end with <code>return</code> or just by reaching the end of
-fiber function.
+
+A fiber has three possible states: running, suspended or dead.
+When a fiber is created with <code>box.fiber.create()</code>,
+it is suspended.
+When a fiber is started with <code>box.fiber.resume()</code>, it is running.
+When a fiber's control is yielded back to the caller with
+<code>box.fiber.yield()</code>, it is suspended.
+When a fiber ends (due to <code>return</code> or by reaching the
+end of the fiber function), it is dead.
     </para>
     <para>
 A fiber can also be attached or detached.
@@ -1048,15 +1051,17 @@ can be used to cancel runaway Lua procedures.
     </para>
     <para>
 The other potential problem comes from detached
-fibers which never get scheduled, because are not subscribed
-to any events, or no relevant events occur. Such morphing fibers
+fibers which never get scheduled, because they are not subscribed
+to any events, or because no relevant events occur. Such morphing fibers
 can be killed with <code>box.fiber.cancel()</code> at any time,
 since <code>box.fiber.cancel()</code>
 sends an asynchronous wakeup event to the fiber,
 and <code>box.fiber.testcancel()</code> is checked whenever such an event occurs.
     </para>
     <para>Like all Lua objects, dead fibers are
-    garbage collected.</para>
+    garbage collected: the garbage collector frees pool allocator
+    memory owned by the fiber, resets all fiber data, and returns
+    the fiber to the fiber pool.</para>
     <varlistentry>
         <term>
             <emphasis role="lua">box.fiber.id(fiber) </emphasis>
@@ -1185,10 +1190,10 @@ logger = cat - >> tarantool.log
 </para>
 
 <section>
-<title>Limitation of stored programs</title>
+<title>Limitation of stored procedures</title>
 
 <para>
-    There are two limitations in stored program support one should
+    There are two limitations in stored procedures support one should
     be aware of: execution atomicity and lack of typing.
 </para>
 <bridgehead renderas="sect4">Cooperative multitasking environment</bridgehead>