Lua: addcitional documentation in the user guide.

doc/developer/developer.xml

@@ -35,6 +35,16 @@ The other alternative, if you have actually modified
   </para>
 </section>
 </chapter>
+
+To build documentation, you'll need:
+
+xsltproc
+docbook5-xml
+docbook-xsl-ns
+libsaxon-java- for saxon processing
+libxml-commons-resolver1.1-java
+libxerces2-java
+libxslthl-java
 <!--
      TOC:
 

doc/user/CMakeLists.txt

@@ -21,7 +21,7 @@ add_custom_target(relink
         user.xml)
 
 add_custom_target(html-saxon
-    COMMAND java -cp "/usr/share/java/saxon.jar:/usr/share/java/xml-commons-resolver-1.1.jar:/usr/share/java/docbook-xsl-saxon.jar:/usr/share/java/xercesImpl.jar:/etc/xml/resolver:/usr/share/java/xslthl.jar"
+    COMMAND java -cp "/usr/share/java/saxon.jar:/usr/share/java/xml-resolver.jar:/usr/share/java/docbook-xsl-saxon.jar:/usr/share/java/xercesImpl.jar:/etc/xml/resolver:/usr/share/java/xslthl.jar"
         -Djavax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
         -Djavax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl
         -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration

doc/user/language-reference.xml

@@ -20,7 +20,7 @@
   <itemizedlist>
     <listitem><para>
       Read/write data port, to handle INSERTs, UPDATEs,
-      DELETEs and SELECTs. This port speaks the native
+      DELETEs, SELECTs and CALLs. This port speaks the native
       Tarantool protocol, and provides full access to the server.
       </para>
       <para>
@@ -46,7 +46,7 @@
         is not started.
       </para></listitem>
     <listitem><para>Memcached port. Optional, read-write data port
-      that speaks Memcached protocol. This port is off by default.
+      that speaks Memcached text protocol. This port is off by default.
     </para></listitem>
   </itemizedlist>
   In absence of authentication, this approach allows system
@@ -55,8 +55,8 @@
   the separation, and <command>tarantool</command> command line
   client automatically selects the correct port for you
   with help of a simple regular expression. SELECTs, UPDATEs,
-  INSERTs and DELETEs are sent to the primary port, whereas SHOW,
-  RELOAD, SAVE and others -- to the administrative port.
+  INSERTs, DELETEs and CALLs are sent to the primary port, whereas
+  SHOW, RELOAD, SAVE and others -- to the administrative port.
 </para>
 
 <section>
@@ -64,15 +64,15 @@
 
   <para>Tarantool protocol was designed with focus on asynchronous
     I/O and easy integration with proxies. Each client
-    request starts with a simple binary header, containing three
+    request starts with a 12-byte binary header, containing three
     fields: request type, length, and a numeric id.
   </para>
   <para>
-    Four basic request types are supported: INSERT, UPDATE, DELETE
-    and SELECT. The mandatory length, present in the header,
-    allows to simplify client or proxy I/O.
+    Five basic request types are supported: INSERT, UPDATE,
+    DELETE, SELECT and CALL. The mandatory length, present in the
+    header, allows to simplify client or proxy I/O.
     The server response to a request always carries in its header
-    the same command type and request id.
+    the same request type and id.
     The id makes it possible to always match request to a
     response, even if the latter arrived out of order.
   </para>
@@ -122,10 +122,10 @@
   <title>Writing stored procedures in Lua</title>
   <para>
     Lua is a light-weight, multi-paradigm embeddable language.
-    Tarantool/Box supports allows user to dynamically define,
-    alter, drop using the administrative console.
-    The procedures can be invoked Lua both from the administrative
-    console and using a binary protocol, for example:
+    Tarantool/Box allows to dynamically define, invoke,
+    alter and drop Lua procedures.
+    The procedures can be invoked both from the administrative
+    console and using the  binary protocol, for example:
 <programlisting>
 tarantool> lua function f1() return 'hello' end
 ---
@@ -149,11 +149,11 @@ Found 1 tuple:
     of the command, is passed into the stored procedure, each
     field of the tuple converted to a string parameter of the
     procedure. As long as currently Tarantool tuples are
-    type-agnostic, Lua strings is chosen as the transport means
+    type-agnostic, Lua strings are chosen as the transport means
     between the server and the interpreter.
   </para>
   <para>
-    Everything value, returned from a stored function by means of
+    Every value, returned from a stored function by means of
     <quote>return</quote> clause, is converted to Tarantool/Box tuple
     and sent back to the client in binary form.
   </para>
@@ -166,7 +166,7 @@ Found 1 tuple:
     to send any kind of request to the server in the binary form.
     Function <quote>box.process()</quote> is a server-side outlet
     for Tarantool binary protocol. Any tuple returned by the
-    server is converted to a Lua object of tupe <quote>box.tuple</quote>
+    server is converted to a Lua object of type <quote>box.tuple</quote>
     and appended to the return list of <quote>box.process()</quote>.
   </para>
   <para>
@@ -186,9 +186,12 @@ Found 1 tuple:
   <section>
   <title>Replication of stored procedures</title>
   <para>
-    The CALL statement itself does not enter Tarantool write ahead
-    log. Instead, the actual updates and deletes, performed by
-    the procedure, generate their own log events.
+    The CALL statement itself does not enter Tarantool Write Ahead
+    Log. Instead, the actual updates and deletes, performed by
+    the procedure, generate their own log events. This ensures
+    that the replica never goes out of sync with the master
+    due to non-deterministic effects of Lua procedures, such
+    as involving current time, I/O, or random functions.
   </para>
   </section>
 </section>

doc/user/tutorial.xml

@@ -25,8 +25,7 @@
        <citetitle xlink:href="http://pypi.python.org/pypi/pexpect/" xlink:title="pure-Python pexpect implementation">python-pexpect</citetitle> modules,</para>
 
       <note><para>
-        Python is used to run regression tests and
-        <command>tarantool</command> command-line client.
+        Python is used to run regression tests.
         If you do not plan to run tests you may skip this step.
       </para></note>
     </listitem>
@@ -35,7 +34,10 @@
   <itemizedlist>
     <listitem><para>CMake 2.6 or newer,</para></listitem>
     <listitem><para>GCC 4.4 or newer, with gcc-objc (ObjectiveC)
-    language frontend.</para></listitem>
+    language frontend,</para></listitem>
+    <listitem><para>libreadline-dev, when compiling the
+    command line client.
+    </para></listitem>
   </itemizedlist>
 </para>
 <para>
@@ -59,7 +61,7 @@
 </para>
 <para>
   Once the server is started, you can connect to it and issue
-  queries using a command line client implemented in Python:
+  queries using a command line client:
   <programlisting>
   <prompt>$ </prompt><command>cd <replaceable>package-name</replaceable>/bin &amp;&amp; ./tarantool</command>
   <prompt>tarantool> </prompt> <userinput>show info</userinput>
@@ -82,11 +84,12 @@
   necessary: configuration and build. The easiest way to configure
   a source directory with CMake is by requesting an in-source build:
   <programlisting>
-  <prompt>$ </prompt><command>cd</command> <filename><replaceable>package-name</replaceable></filename> &amp;&amp; <command>cmake</command> .</programlisting>
+  <prompt>$ </prompt><command>cd</command> <filename><replaceable>package-name</replaceable></filename> &amp;&amp; <command>cmake</command><option> . -DENABLE_CLIENT=true</option></programlisting>
   Upon successful configuration, CMake prints the status
   of optional features:
   <programlisting>
   -- *** The following options are on in this configuration: ***
+  -- ENABLE_CLIENT: true 
   -- ENABLE_GCOV: ON
   -- ENABLE_TRACE: ON
   -- ENABLE_BACKTRACE: ON
@@ -108,14 +111,14 @@
   It will create necessary files in directory
   <filename>./test/var/</filename>, and fire off the server with
   minimal configuration.
-  The command line client is located in the same directory:
-  <programlisting><prompt>$ </prompt><command>./test/tarantool</command></programlisting>
+  The command line client is located in <filename>client/tarantool</filename>:
+  <programlisting><prompt>$ </prompt><command>./client/tarantool/tarantool</command></programlisting>
 </para>
 <sidebar>
 <para>
   Congratulations, you have the server up and running.
   Check out the remaining chapters of this manual to learn
-  more about available commands, contents of
+  about available commands, contents of
   <filename>tarantool.cfg</filename>,
   replication and high availability with Tarantool.
 </para>